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Summary of Changes for Version 6.0 






3151 Display Terminal 

• Chapter 3, "Customizing the Session Manager," has been updated to include 
the 3151 display terminal in all 31xx display references. 

Extended Address Mode Support 

• In Chapter 8, "Techniques for Improving Performance," the SUPVIO mapping 
example has been updated to include systems with extended address mode. 

• Screens and examples throughout this document have been updated for extended 
address mode support. 

System Partition Statements 

• References to the SYSTEM statement have been replaced by the appropriate 
system partition statement: SYSPARTS, SYSPARMS, SYSCOMM, or 
SYSEND. 

Editorial/Usability Changes 

• Numerous editorial and usabiHty changes have been made throughout this book. 

• In Chapter 8, "Techniques for Improving Performance," information on loading 
$MEMDISK has been removed from this document and added to the Operator 
Commands and Utilities Reference. 
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About This Book 



Audience 



This book describes how to extend or enhance some of the Event Driven Executive 
(EDX) software facihties to meet your own requirements. 



This book is intended for appHcation programmers who write and maintain 
programs using the Event Driven Language (EDL). Readers should be famihar with 
the language before using this book. You can learn EDL by using the Event Driven 
Executive Language Programming Guide. 

The Internal Design can assist you in understanding some of the topics presented. 
Other topics will require you to be famihar with assembler language programming 
and hardware control blocks. 



How This Book Is Organized 

This book contains nine chapters: 



o 



Chapter 1, "What is Customization?" presents an overview of the facihties you 
can enhance or extend and gives some ideas you can implement. 

Chapter 2, "Adding Your Own Operator Command" describes how to create a 
new operator command. It explains design considerations and includes several 
coding examples. 

Chapter 3, "Customizing the Session Manager" shows how to add options and 
build menus that run under the session manager. This chapter also presents 
several different techniques you can use when you add an option. 

Chapter 4, "Adding Your Own Task Error Exit Routine" describes how you 
can pass control from a main program to an error-handling routine when a 
program check occurs. 

Chapter 5, "Running Programs and Initialization Routines at IPL" shows three 
different methods that execute your code as part of the IPL process. 

Chapter 6, "Adding Your Own Device Support" shows an approach to 
I/O-level programming through the use of EXIO. This chapter shows a 
technique you can use to extend the function of a supported device to meet your 
needs. 

Chapter 7, "Creating Your Own EDL Instruction" explains how to build and 
add your own EDL instruction to the EDL instruction set. 

Chapter 8, "Techniques for Improving Performance" presents several methods 
for improving the performance of your system. 

Chapter 9, "Customizing Partitions" shows several methods for customizing 
partitions when you have written a supervisor routine that needs to reside in a 
static portion of the supervisor. 



About This Book IX 



Aids in Using This Book 



liH 

This book contains the following aids to using the information it presents: 

• A table of contents that lists the main headings in the book. 

• In the step-by-step procedures, several utihties are used and the interactive 
display screens are shown. Any responses you must make in answer to a prompt 
are shown in red. 

• An index of the topics covered in this book. 



Using the Enter and Attention Keys 



This book uses the term "enter key" to mean the key that indicates that you have 
completed input to a screen and want the system to process data keyed in. It uses 
the term "attention key" to mean the key that indicates that you want to direct 
keyboard input to the operating system supervisor. If your keyboard does not have 
these keys, use the corresponding keys on your keyboard. 



A Guide to the Library 



Refer to the Library Guide and Common Index for information on the design and 
structure of the EDX Hbrary, for a bibliography of related pubhcations, for a 
glossary of terms and abbreviations, and for an index to the entire hbrary. 



Contacting IBIVI about Problems 



^ 



You can inform IBM of any inaccuracies or problems you find with this book by 
completing and mailing the Reader's Comment Form provided in the back of the 
book. 

If you have a problem with the Series/ 1 Event Driven Executive, refer to the IBM 
Series! 1 Software Service Guide, GC34-0099. 



/^ 
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What is Customization? 



Chapter!. What is Customization? 






The Event Driven Executive (EDX) consists of a variety of software support you can 
use in your application. In addition, you can use tools such as utihties to assist you 
in your operating environment. However, this IBM-supplied software may not 
provide all the features you require for your application. You can extend or modify 
the function of several of these facilities to meet your specific operational or 
application requirements. Extending or modifying these facilities is called 
customization. 

This book describes how you can customize some of the EDX software. It also 
includes a discussion on techniques to improve performance on your Series/ 1. 

Whenever you customize any of the facilities, you should always copy the changes 
onto a diskette or tape. A subsequent release of EDX or a program temporary fix 
(PTF) could possibly overlay any customization changes you make to your current 
release of EDX. 

This chapter introduces the facilities you can customize and presents an overview of 
the performance information presented in this book. 



What You Can Customize 

This book presents some examples of when you might consider customization. You 
can customize the following facilities to meet your needs. 

Operator Commands 

You can create your own operator command to perform a function not available 
with the existing operator commands. For example, you could create an operator 
command that displays your terminal name and hardware address. On a Series/ 1 
with many terminals attached, this information could be useful. 

Chapter 2, "Adding Your Own Operator Command," contains detailed information 
on how to create your own operator command. 

Session Manager 

You can add your application as a new option on an option menu. Further, you 
can create your own menu screens and procedures to match your application. 

Chapter 3, "Customizing the Session Manager," discusses this type of 
customization. 

Task Error Exits 

You might consider adding your own task error exit routine to an EDL program. 
For example, you may want to do this if the system-suppHed routine does not yield 
all the information you need. 

Chapter 4, "Adding Your Own Task Error Exit Routine," explains how you can 
perform this type of customization. 
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Initialization Routines 

You can add initialization routines to your system to perform various tasks when 
you IPL the Series/1. For example, you could have "program A" loaded in partition 
1 and the session manager loaded in partition 2. In addition, you could supply a 
routine to initialize new devices attached to the Series/ 1. 

Chapter 5, "Running Programs and Initiahzation Routines at IPL," discusses this 
type of customization. 

Device Support 

You can extend the system's I/O interface by supplying your own device support. In 
this way you can access additional devices not supported under EDX or you can 
extend the device support EDX does provide. 

Chapter 6, "Adding Your Own Device Support," explains the procedures required 
to implement such device support. 

EDL Instructions 

You can create your own EDL instruction to perform operations not available with 
the existing EDL instruction set. 

Chapter 7, "Creating Your Own EDL Instruction," discusses the details of how to 
do this. 



Improving Performance 



Partitions 



You can increase the performance of your system or apphcation in various ways. 
For example, you can decrease the time it takes the supervisor to access a volume. 
You can also decrease the compilation time for SEDXASM. 

Chapter 8, "Techniques for Improving Performance," discusses these topics. 



If you have written a supervisor module that performs I/O into itself, performs I/O 
from itself, or contains one or more data set control blocks (DCBs), the module 
must reside in a static portion of the supervisor. 

Chapter 9, "Customizing Partitions," discusses various ways to customize partitions. 



o 
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Chapter 2. Adding Your Own Operator Command 

If you need a function that is not supported by the existing operator commands, you 
can create your own routine to perform that function. EDX provides you with an 
interface that enables you to include your routine in the supervisor. The $U 
command is reserved for your use. When you add your routine and issue $U, the 
system uses the new function. 

This chapter explains the steps required to add your own operator command. 

Designing and Coding Your Routine 

Operator commands run as an ATTNLIST program. Therefore, you must adhere to 
certain design considerations when you code the routine. A discussion of these 
design considerations follows. 

1. You must specify MAIN = NO on the PROGRAM statement of your routine. 

2. Code an ENTRY statement specifying SUSRCMD following the PROGRAM 
statement. This statement identifies the entry point to which control is passed 
when your routine is called. Optionally, you can specify a CSECT statement 
following the PROGRAM statement. The label you specify can be 1 - 8 
characters. 

Note: You can omit the ENTRY statement if you use SUSRCMD as the label 
of the CSECT statement. 

Specify the name SUSRCMD as the label of your routine. The executable code 
you provide begins at this label. 

3. You should design your routine so that it executes quickly. Doing this can 
prevent possible degradation in execution of other tasks. The following 
instructions are not recommended for use in your routine: 

ENQT/DEQT 

READ/WRITE 

STIMER 

WAIT 

LOAD 

DETACH 

ENDTASK 

TP 

PROGSTOP. 

You must code an END ATTN instruction following the last executable 
statement in your routine. 
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4. The END statement must be the last statement in your routine. 
Using these design considerations, your source code would look as follows: 



NEWCMD 


PROGRAM 


MAIN=NO 




ENTRY 


$USRCMD 


SUSRCMD 


EQU 


* 




( 


source code for your routine) 




ENDATTN 






END 





Some Features You Can Include 

You can provide various features in your operator command, 
examples illustrate two features you could provide. 



The following 



Operator Command for a Specific Terminal 

You may want to restrict the function of the operator command to a specific 
terminal, such as $SYSLOG. By obtaining the name of the terminal (located in the 
CCB) that issues the command, you could compare the name from the CCB against 
"SSYSLOG" and branch to an exit upon a "no match" condition. This requires a 
cross-partition MOVE, with FKEY = 0, because the CCB information resides in 
address space (partition 1). 

The following example illustrates how you can obtain and compare terminal names: 



'v^ 



FETCH 


PROGRAM MAIN=NO 




ENTRY SUSRCMD 




PRINT OFF 




COPY CCBEQU CCB EQUATES 




PRINT ON 


SUSRCMD 


TCBGET #1,$TCBCCB GET ADDR OF CCB 




MOVE TNAME, ($CCBNAME,#1), (8, BYTES), FKEY=0 GET NAME 




IF (TNAME, NE,SYSLOG, 8), GOTO, EXIT $SYSLOG? 




• (perform function) 


EXIT 


ENDATTN 


TNAME 


TEXT LENGTH=8 




END 



^^ta-i^ 
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Multifunction Operator Command 

You might want to have an operator command that provides more than one 
function. The function executed could depend on the operator input when the 
program issues the command. For example, the operator could enter $U A and the 
system would execute the code at label RTNA. Similarly, if the operator enters $U 
B, the system executes RTNB; it executes RTNC when the operator enters $U C. 
Because no message text is coded on the READTEXT, you must specify A, B, or C 
when you issue the command. 

An example of how you could develop a multifunction operator command (three 
routines) follows: 






MULTI 


PROGRA^ 


1 MAIN=NO 




ENTRY 


$USRCMD 


$USRCMD 


READTEXT CMD,PROMPT=COND GET OPER REQUEST 




IF 


(CMD, EQ,C'A', BYTE), GOTO, RTNA 




IF 


(CMD,EQ,C'B',BYTE),GOTO,RTNB 




IF 


(CMD, EQ,C"C', BYTE), GOTO, RTNC 




GOTO 


EXIT INVALID REQUEST 


RTNA 


EQU 

• 
• 
9 


* 
(perform routine A) 




GOTO 


EXIT 


RTNB 


EQU 

• 
• 


* 
(perform routine B) 




GOTO 


EXIT 


RTNC 


EQU 

• 
• 


* 
(perform routine C) 


EXIT 


ENDATT^ 


1 


CMD 


TEXT 
END 


LENGTH=2 
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Testing Your Routine 



After you design and code your routine, you should test it. By testing your routine 
first and verifying that it gives you the desired results, you can avoid including an 
inaccurate routine in your supervisor. 

You can use the following sample program to verify that your routine meets your 
requirements: 



CMDTST 


PROGRAM 


START 






EXTRN 


$USRCMD 


POINTS TO YOUR RTN 




ATTNLIST 


(GO, SUSRCMD, STOP, STOP) 




START 


WAIT 
PR06ST0P 


ATTNECB, RESET 




ATTNECB 


ECB 






STOP 


POST 
ENDATTN 
ENDPROG 
END 


ATTNECB 


TELL IT WHEN TO QUIT 



To test your routine using the sample program, you must do the following: 

1. Assemble the sample program (CMDTST) using $EDXASM. The assembled 
output from this step will be used in step 3. 

2. Assemble your routine using $EDXASM. The assembled output from this step 
will be used in step 3. 

3. Link edit the assembled output from steps 1 and 2 using SEDXLINK. The 
assembled output from step 1 must be specified on the first INCLUDE 
statement. 

4. Upon a successful link edit ( — 1 completion code), load the program you 
specified during Hnk editing. 

5. Call your routine by pressing the attention key and entering GO. Press the 
attention key and enter STOP to end the program. 






After running the test program, you can determine whether your routine executed 
you expected. If the test is successful, you must include your routine in the 
supervisor. 



as 
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Including Your Routine in the Supervisor 

After a successful test of your new operator command routine, you must link edit 
your routine into the supervisor. This section explains how to do this. 

Editing Your System INCLUDE Data Set 

If you performed a tailored system generation, edit the data set that defines the 
supervisor modules currently in your supervisor (normally LINKCNTL on 
EDX002). Otherwise, you must edit $LNKCNTL. Insert the name of the data set 
and volume containing your routine's assembled output (from step 2 of testing 
section) just before the module EDXINIT. For example, if your assembled output 
module is named CMDOBJ on volume EDX002, the INCLUDE statement would be 
as follows: 






• 
• 
• 

INCLUDE 


CMDOBJ, EDX002 




YOUR 


NEW OPERATOR COMMAND 


INCLUDE 


EDXINIT 


*24* 


SUPERVISOR INITIALIZATION 


INCLUDE $OVLMGR0 


*25* 


OVERLAY MANAGER 


*INCLUDE 

• 
• 
• 


RW4963ID 


*3* 


4963 


FIXED HEAD REFRESH SUPPORT 



After inserting the new INCLUDE statement, save the edited data set in 
LINKCNTL on EDX002. Next, load SJOBUTIL and specify SUPPREPS when 
prompted for a data set. SUPPREPS will generate a new supervisor containing your 
operator command. 

Upon completion of the system generation, check the link-map listing. The link map 
will contain the entry and address of SUSRCMD if your routine is contained in the 
supervisor. In addition, if you specified SUSRCMD as the label on a CSECT 
statement, this address will appear also. Initialize your new supervisor (II command 
of SINITDSK) and IPL the system. You can now call your routine using $U as a 
new operator command. 

If SUSRCMD appears as an unresolved EXTRN, the ENTRY or CSECT statement 
specifying SUSRCMD was omitted in your routine. You must compile and test the . 
routine again, then perform another system generation. 
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Operator Command Examples 



The following are examples of routines you could use as operator commands: 



Message Broadcast Routine 



This routine sends a broadcast message to three terminals. The routine is restricted 
to $SYSLOG. The message text can be up to 60 characters in length. If any of the 
terminals are in use when the message is sent, the operator is notified. Terminals in 
use do not receive the broadcast message. You supply the message text when you 
issue the $U command, for example: 
"$U SYSTEM IPL IN 5 MINUTES.... OPER" 



BCAST 


PROGRAM 

ENTRY 

PRINT 


MAIN=NO 
$USRCMD 
OFF 








COPY 


CCBEQU 




CCB EQUATES 




PRINT 


ON 






$USRCMD 


EQU 


* 








TCBGET 


#1,$TCBCCB 




GET CCB ADDR 




MOVE 


TNAME, ($CCBNAME,#1), 


(8,BYTES),FKEY=0 GET NAME 




IF 


(TNAME, NE, SYSLOG, 8), 


GOTO, 


EXIT $SYSLOG 




READTEXT 


MSG, PROMPT=COND, MODE 


>LINE 


READ MESSAGE 




MOVEA 


#2,LIST+2 




POINT TO NAMES 




DO 


3, TIMES 








MOVE 


TNAME, (0, #2), (8, BYTES) 


MOVE NAME FROM LIST 




ENQT 


TNAME, BUSY=BSYRTN 




ENQT TERM 




PRINTEXT MSG 




SEND MESSAGE 




DEQT 










ADD 


#2,10 




INCREMENT INDEX 




GOTO 


NDU 




BRANCH AROUND BUSY 


BSYRTN 


EQU 


* 




BUSY ROUTINE 




ENQT 


SSYSLOG 




NOTIFY OPER. WHICH 




PRINTEXT (0,#2) 




TERMINAL IS BUSY 




PRINTEXT ' IS BUSY' 








DEQT 










ADD 


#2,10 




INCREMENT INDEX 


NDU 


ENDDO 








EXIT 


ENDATTN 








LIST 


EQU 
TEXT 
TEXT 
TEXT 


* 

'TERM1',LENGTH=8 
'TERM2',LENGTH=8 
'TERM3',LENGTH=8 




LIST OF TERM NAMES 


SYSLOG 


TEXT 


'$SYSL0G',LENGTH=8 






MSG 


TEXT 


LENGTH=60 




MSG HOLD AREA 


TNAME 


lOCB 
END 









/' 
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Display Terminal Name and Address Routine 

The following routine displays the terminal name and its address on the terminal 
from which you issue the command: 



TERMID 


PROGRAM 


MAIN=NO 






ENTRY 


$USRCMD 






PRINT 


OFF 






COPY 


CCBEQU CCB EQUATES 






PRINT 


ON 




$USRCMD 


EQU 


* 






TCBGET 


#1,$TCBCCB 






MOVE 


TNAME, ($CCBNAME,#1) , (8,BYTES) ,FKEY=0 


NAME 




MOVE 


TADDR+1,($CCBPREP+1,#1),(1, BYTES), FKEY=0 


ADDR 




PRINTEXT 


'@TERM ID ADDR0' 






PRINTEXT 


TNAME PRINT NAME 






PRINTNUM 


TADDR, MODE=HEX PRINT ADDR 






PRINTEXT 


■@' 






ENDATTN 






TNAME 


TEXT 


LENGTH=8 




TADDR 


DATA 
END 


F'O' 
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Chapter 3. Customizing the Session IVIanager 

The session manager provides a set of menu screens and procedures that make EDX 
utilities available for your use. The menu screens enable you to select options 
(programs) or enter parameters. The procedures load the programs you select. By 
customizing the session manager, you can make a commonly-used program a part of 
a session manager menu. You can do this by modifying existing menus or by 
creating new menus. 

This chapter describes how you customize the session manager. This chapter uses a 
hypothetical application named PAYROLL to show you how to run a program from 
a newly created menu. 

Before you add an application to the session manager, you must ensure the partition 
in which you load the session manager has enough storage. In addition, you must 
understand the naming conventions of session manager menus and procedures. You 
must adhere to these conventions when you add menus and procedures. 



How Big Should the Partition Be? 






The session manager requires a minimum partition of 16K bytes of storage. When a 
program, called by the session manager, begins execution, the session manager frees 
14K bytes of storage. The program you call through the session manager must not 
require more than the partition size minus 2K bytes of storage. For example, if your 
program requires 34K bytes of storage, the partition must contain at least 36K bytes 
of available storage. 



How to Name New Menus and Procedures 



Session manager menus and procedures are structured in a hierarchy. The names 
used for these menus and procedures reflect their level within the hierarchy. Three 
levels exist: 

Primary Loads programs or presents secondary option menus 

Secondary Loads programs or presents parameter input menus 

Tertiary Passes parameters and loads programs. 

Menu names must begin with the prefix $SMM. Each menu must have a 
corresponding procedure. Procedure names must begin with the prefix $SMP. 

The menu and procedure names also contain numbers. These numbers are used to 
indicate the level and option number of the menu. For example, a menu or 
procedure name containing two numbers indicates the secondary level. Menus or 
procedures with four numbers indicate the tertiary level. 
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An example of the naming convention hierarchy follows. The example illustrates the 
hierarchy for the $EDXASM option under the program preparation option: 



Primary 
Option 
Menu 
Number 


Secondary 
Option 
Menu 
Name 


Secondary 
Procedure 
Name 


Secondary 
Option 
Menu 
Number 


Parm 
Menu 
Name 


Procedure 

(SJOBUTIL) 

Name 


Option 2 


$SMM02 


$SMP02 


Option 2 


$SMM0202 


$SMP0202 



Figure 3-1. Naming Convention Example 

Figure 3-2 illustrates the various paths through which you can call programs under 
the session manager. You can choose any of these paths to call programs when you 
add a new option. 
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Figure 3-2. Paths Through the Session Manager 
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Adding an Option to the Primary Option IVIenu 

The primary option menu SSMMPRIM is the first menu presented after you enter 
your session manager logon ID. You can update this menu to add your program as 
an option. 

This section describes how you can add a program name PAYROLL to the primary 
option menu. All the following steps use EDX utilities through the session manager. 

To add PAYROLL to the primary option menu: 

1 . Select option 4.4 from the primary option menu. This option loads the 
SIMAGE utihty. 

2. Define a null character when the COMMAND (?) prompt appears by entering: 
COMMAND (?): NULL # 



Note: You can define any character as the null character except for a blank or a 
character that has already been defined as an attribute character. 

3. Specify the menu to edit when the COMMAND (?) prompt appears by entering: 
COMMAND (?): $SMMPRIM,EDX002 



v_ 



The primary option menu $SMMPRIM appears next on the terminal screen. 

4. Press the PFl key to display the protected fields of menu $SMMPRIM as 
unprotected fields. This enables you to modify the menu. The null character, #, 
defined in step 2 represents the input data fields. 

5. Position the cursor under the last option number and add the text for the new 
option, option 1 1 — PAYROLL. 
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6. Press the enter key. The enter key takes you out of edit mode. The 
newly-defined menu image appears as shown in Figure 3-3. 



$SMMPRIM: SESSION MANAGER PRIMARY OPTION MENU— 

ENTER/SELECT PARAMETERS: PRESS PF3 TO EXIT 



SELECT OPTION ==> 

1 - TEXT EDITING 

2 - PROGRAM PREPARATION 

3 - DATA MANAGEMENT UTILITIES 

4 - TERMINAL UTILITIES 

5 - GRAPHICS UTILITIES 

6 - EXEC PROGRAM/UTILITY 

7 - EXEC $JOBUTIL PROC 

8 - COMMUNICATION UTILITIES 

9 - DIAGNOSTICS AIDS 

10 - BACKGROUND JOB CONTROL UTILITIES 

11 - PAYROLL 



Figure 3-3. Updated Session Manager Primary Option Menu 

7. Press the PF3 key to return to the SIMAGE command mode. In response to the 
COMMAND (?) prompt, enter: 



V. 



COMMAND (?): SAVE $SMMPRIM,EDX0G2 



V,. 



y 



8. In response to the message: 



SHOULD THE 31XX INFORMATION BE SAVED (Y/N)? 



reply N if you want to save a 4978/4979/4980 screen image only. Reply Y to 
this message if you are using the ATTR command of SIM AGE to define a 31xx 
screen image. Refer to the Operator Commands and Utilities Reference for 
details on the ATTR command of SIMAGE. 

Note: A 31xx screen image is used for a 3101, 3151, 3161, 3163, or 3164 
terminal. 

At this point, the system saves the updated primary option menu. Enter EN to end 
the $IMAGE utility. The session manager displays the updated primary option 
menu with the PAYROLL option. 

Do You Require Additional l\/lenus? 

If you are loading a program directly from the primary option menu, you must 
update the session manager primary procedure. The section "Updating the Primary 
Procedure" on page 3-19 describes how you can do this. 



3-4 SC34-0942 



Customizing the Session Manager 



You can design your new option on the primary option menu so that it consists of 
several options. To do this, you must create a secondary option menu. The section 
"Modifying or Creating a Secondary Option Menu" describes how you can do this. 

If your program requires input parameters at execution time, you must create a 
parameter input menu to pass the parameters. The section "Creating a Parameter 
Input Menu" on page 3-9 describes how you can do this. 



Modifying or Creating a Secondary Option Menu 

This section describes how you can add a new option to an existing secondary 
option menu or create your own menu with options. The method you use to add 
options is similar. 

Adding an Option to a Secondary Option Menu 

If you want to add your program as an option to a category of programs, you must 
update an existing secondary option menu. 

The following list shows the existing secondary option menus you can update and 
their categories: 



Menu 
Name 


Category 


$SMM02 


Program preparation 


$SMM03 


Data management 


$SMM04 


Terminal utilities 


$SMM05 


Graphics utiUties 


$SMM08 


Communication utilities 


$SMM09 


Diagnostic aids 


SSMMIO 


Background job control 



Figure 3-4. Existing Secondary Option Menus 
Note: All these menus reside on EDX002. 
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If, for example, you want to add an option that combines both $EDXASM and 
SUPDATE into one option to the program preparation secondary option menu 
($SMM02), you must: 

1 . Select option 4.4 from the primary option menu. This option loads the 
SIMAGE utility. 

2. Define a null character when the COMMAND (?) prompt appears by entering: 



COMMAND {?): MULL # 



Note: You can define any character as the null character except for a blank or a 
character that has already been defined as an attribute character. 

3. Specify the menu to edit when the COMMAND (?) prompt appears by entering: 



COMMAND (?) 



$SMM02,EDX002 



The secondary option menu $SMM02 appears next on the terminal screen. 

4. Press the PFl key to display the protected fields of menu $SMM02 as 
unprotected fields. This enables you to modify the menu. The null character, #, 
defined in step 2 represents the input data fields. 

5. Position the cursor under the last option number and add the text for the new 
option, option 15 - $EDXASM/$UPDATE. 

6. Press the enter key. The enter key takes you out of edit mode. The 
newly-defined menu image appears as shown in Figure 3-5. 



c. 



y 



$SMM02 SESSION MANAGER PROGRAM PREPARATION OPTION MENU- 
ENTER/SELECT PARAMETERS: PRESS PF3 TO RETURN 



SELECT OPTION ==> 










1 


- $EDXASM COMPILER 






2 


- $EDXASM/$EDXLINK 






3 


- $S1ASM ASSEMBLER 




4 • 


- $COBOL COMPILER 




5 


- $FORT FORTRAN COMPILER 




6 - 


- $PLI COMPILER/IEDXLINK 




7 


- SEDXLINK LINKAGE EDITOR 




8 


- $XPSLINK LINKAGE E 


DITOR FOR 


SUPERVISOR 


9 


- $UPDATE 








10 


- SUPDATEH (HOS" 


D 






11 


- $PREFIND 








12 


- $PASCAL COMPIl 


-ER/$ 


EDXLINK 


13 


- $EDXASM/$XPSLINK FOR SUPERVISORS 


14 


- $MSGUT1 MESSAGE SOURCE PROCESSING UTILITY 


15 


- $EDXASM/$UPDA- 


rE 









Figure 3-5. Updated Program Preparation Secondary Option Menu 
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7. Press the PF3 key to return to the $IMAGE command mode. In response to the 
COMMAND (?) prompt, enter: 



COMMAND (?): SAVE $SMM02,EDX002 

V 



8. In response to the message: 
SHOULD THE 31XX INFORMATION BE SAVED (Y/M)? 



V_ 



reply N if you want to save a 4978/4979/4980 screen image only. Reply Y to 
this message if you are using the ATTR command of SIM AGE to define a 31xx 
screen image. Refer to the Operator Commands and Utilities Reference for 
details on the ATTR command of SIMAGE. 

Note; A 31xx screen image is used for a 3101, 3151, 3161, 3163, or 3164 
terminal. 

At this point, the system saves the updated secondary option menu. Use the EN 
command to end the SIMAGE utility. 

Creating a Secondary Option IVIenu 

This section describes how you can create a new secondary option menu. 

Assume the newly-defined PAYROLL appUcation (option 1 1 of primary option 
menu) consists of a maihng Ust program and a program to print paychecks. To 
create a menu with these programs as options: 

1. Select option 4.4 from the primary option menu. This option loads the 
$IMAGE utiUty. 

2. Define a null character when the COMMAND (?) prompt appears by entering: 
i COMMAND (?): MULL § 



Note: You can define any character as the null character except for a blank or a 
character that has already been defined as an attribute character. 

3. Define the screen dimensions as 24 by 80 (full screen) by entering: 
COMMAND (?): DIMS 24 80 



4. Enter the command EDIT. A blank screen appears. 

5. Press the PFl key. 
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6. Enter the text for your menu. You must use the null character (defined in step 
2) to specify input data fields. Enter eight null characters following the 
SELECT OPTION prompt. The secondary option menu for the PAYROLL 
looks as follows: 

$SMM11 PAYROLL APPLICATION SECONDARY OPTION MENU-- 
ENTER/SELECT PARAMETERS: PRESS PF3 TO RETURN 

SELECT OPTION ==> HH^n* 

1 - MAILLIST 

2 - PAYCHK 



Figure 3-6. Sample Secondary Option Menu 

7. Press the enter key after you complete the design of your menu. The enter key 
takes you out of edit mode. 

8. Press the PF3 key to return to the $IMAGE command mode. 

9. Save your new menu when the COMMAND (?) prompt appears by entering: 



V. 



COMMAND (?): SAVE $SMM11,EDX002 



Note: Use the option number in the name of all related menus. For example, 
secondary option menu $SMM11 corresponds to option 11 of the primary 4^ 

option menu. See the section "How to Name New Menus and Procedures" on ^\^ 

page 3-1 for an explanation of how to name menus. 

10. In response to the message: 
SHOULD THE 31XX INFORMATION BE SAVED (Y/N)? 



reply N if you want to save a 4978/4979/4980 screen image only. Reply Y to 
this message if you are using the ATTR command of $IMAGE to define a 31xx 
screen image. Refer to the Operator Commands and Utilities Reference for 
details on the ATTR command of SIMAGE. 

Note: A 31xx screen image is used for a 3101, 3151, 3161, 3163, or 3164 
terminal. 

At this point, the system saves the new secondary option menu. Use the EN 
command to end the SIMAGE utihty. 

Do You Require a Parameter Input Menu? 

If you are loading a program directly from a secondary option menu, you must 
update the session manager primary and secondary procedure. The section 
"Updating the Primary Procedure" on page 3-19 describes how you can do this. 

If your program requires input parameters at execution time, you must create a 
parameter input menu to pass the parameters. The section "Creating a Parameter 
Input Menu" on page 3-9 describes how you can do this. 
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Creating a Parameter Input Menu 






A parameter input menu enables you to pass parameters to the program you want to 
use. You can use these menus to specify and pass parameters such as data set 
names, program options, or an output device. 

This section shows how to create a parameter input menu for the PAYROLL option 
and the combined SEDXASM and $UPDATE option. 

Assume that the PAYCHK program from the PAYROLL secondary option menu 
requires three parameters at execution time. The parameters are an input data set, 
an output data set, and the period end date. To create a menu to pass these 
parameters: 

1 . Select option 4.4 from the primary option menu. This option loads the 
SIMAGE utihty. 

2. Define a null character when the COMMAND (?) prompt appears by entering: 
COMMAND (?): NULL # 



Note: You can define any character as the null character except for a blank or a 
character that has already been defined as an attribute character. 

3. Define the screen dimensions as 24 by 80 (full screen) by entering: 
COMMAND (?): DIMS 24 80 



V_ 



4. Enter the command EDIT. A blank screen appears. 

5. Press the PFl key. 

6. Enter the text for your menu. The null character, #, defined in step 2 represents 
the input data fields. The menu allows for 15 null characters for the data set 
and volume name separated by a comma. The parameter input menu for 
PAYCHK looks as follows: 



$SMM1102: PAYCHK PARAMETER INPUT MENU 

ENTER/SELECT PARAMETERS: PRESS PF3 TO RETURN 



INPUT DATA SET (NAME, VOLUME) ==> ############### 
OUTPUT DATA SET (NAME, VOLUME) ==> ############### 
PERIOD ENDING (MM/DD/YY) ==> ####?### 

Figure 3-7. Sample Parameter Input Menu 
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7. Press the enter key after you complete the design of your menu. The enter key 
takes you out of edit mode. 

8. Press the PF3 key to return to the $IMAGE command mode. 

9. Save your new menu by entering: 



COMMAND (?): SAVE $SMM1102,EDX002 



Note: Use the option number in the name of all related menus. For example, 
parameter input menu $SMM1102 corresponds to option 2 of the secondary 
option menu ($SMM11). If your program does not use a secondary option 
menu, you would name this menu SSMMll. See the section "How to Name 
New Menus and Procedures" on page 3-1 for an explanation of how to name 
menus. 

10. In response to the message: 
SHOULD THE 31XX INFORMATION BE SAVED (Y/N)? 



reply N if you want to save a 4978/4979/4980 screen image only. Reply Y to 
this message if you are using the ATTR command of $IMAGE to define a 31xx 
screen image. Refer to the Operator Commands and Utilities Reference for 
details on the ATTR command of $IMAGE. 

Note: A 31xx screen image is used for a 3101, 3151, 3161, 3163, or 3164 

terminal. A^V 

At this point, the system saves the new parameter input menu. End the $IMAGE 
utility (EN command). 

The next step is to write a procedure to pass parameters. See "Writing a Procedure 
to Pass Parameters" on page 3-11. 
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The same steps are required to create a parameter input menu for the 
$EDXASM/$UPDATE option discussed in the section "Adding an Option to a 
Secondary Option Menu" on page 3-5. You can design the menu as shown in 
Figure 3-8. You must save this menu in a data set named $SMM0215. 



$SMM0215 SESSION MANAGER $EDXASM PARAMETER INPUT MENU 
ENTER/SELECT PARAMETERS: PRESS PF3 TO RETURN 



SOURCE INPUT (NAME, VOLUME) ==> ############### 

OBJECT OUTPUT (NAME<VOLUME) ==> ############### 

OPTIONAL PARAMETERS ==> ################## {up to 64) 
(SELECT FROM LIST BELOW) 



PARAMETERS: 
NOLIST 

LIST TERMINAL-NAME 
ERRORS TERMINAL-NAME 
CONTROL DATASET. VOLUME 
OVERLAY NO. 



DESCRIPTION: 
SUPPRESS LISTING 
USE LIST * FOR THIS TERMINAL 
USE ERRORS * FOR THIS TERMINAL 
$EDXASM LANG. CTRL DATA SET 
NUMBER OF OVERLAY AREAS 



$UPDATE PARAMETER INPUT MENU 



PROGRAM OUTPUT (NAME, VOLUME) 
REPLACE (YES IF PGM EXISTS) 
LISTING (TERMINAL NAME/*) 



==> ############### 

==> ### 

==> ######## 



Figure 3-8. $EDXASM and SUPDATE Parameter Input Menu 



Writing a Procedure to Pass Parameters 



You must write a procedure whenever you pass parameters to your program from a 
parameter input menu. A procedure consists of two parts: 

• PARAMETER section 

• SJOBUTIL control statements. 

To begin writing the procedure: 

1. Select option 1, text editing, from the primary option menu. This loads the 
SFSEDIT utihty. 

2. Select option 2 and enter the statements you require for your application. 
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Writing the PARAMETER Section 

The PARAMETER section of the procedure consists of statements unique to the 
session manager. The PARAMETER statement must be the first statement of your 
procedure. This section must end with an END statement. 

Contained within the PARAMETER section are &PARMnn and &SAVEnn 
statements. The &PARMnn statements enable your procedure to refer to 
parameters entered on the menu. The optional &SAVEnn statements save the 
parameters you enter from session to session. 

&PARMnn Statements 

You can assign a &PARMnn name to each parameter entered on the parameter 
input menu, where nn is the parameter's position number on the menu. You use 
these names on your $JOBUTIL control statements. Each input field on the menu 
represents a parameter. For example, MYDS,MYVOL in the field below represents 
a single parameter and would be assigned the name &PARM01. 



DATA SET, VOLUME 



MYDS.MYVOL 



You assign numbers to parameters in ascending order, from left to right, top to 
bottom. For example, if a menu contains two parameter entries, you assign the 
names &PARM01 (first) and &PARM02 (second). The session manager always 
assigns the name &PARMOO to the 1-4 character session logon ID. 



You must end a &PARMnn statement with a period whenever blanks immediately 
follow that statement. 



V^'' 



The statements of a procedure that reference two menu entries would look as 
follows: 



PARAMETER 
&PARMei. 
&PARM02. 
END 



The session manager substitutes the &PARMnn names with the actual parameters 
you enter on the menu. You can use the &PARMnn statements in conjunction with 
the &SAVEnn statements. 
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&SAVEnn Statements 

The &SAVEnn statements in the procedure enable you to save parameters entered 
on the menu from session to session. The session manager substitutes &SAVEnn 
statements with the actual parameters entered on the menu. You can use these 
statements to save parameters for the menus you create. Once you save a parameter 
from a menu, the parameter will reappear the next time you access that menu. 



The statements of a procedure that reference and save two menu entries would look 
as follows: 



PARAMETER 
&PARM01,&SAVE01 
&PARMO2,&SAVE02 
END 






The statement numbers &SAVE61 -&SAVE90 are reserved for your use. Use these 
statement numbers to save parameters from parameter input menus you create. 

An example of how to use these statement numbers for the PAYCHK parameter 
input menu (Figure 3-7 on page 3-9) follows: 



PARAMETER 




&PARM01,&SAVE61 


(input data set) 


&PARM02,&SAVE62 


(output data set) 


&PARM03,&SAVE63 


(period end date) 


END 





The menu input fields for EDX utilities have preassigned &SAVE statement numbers 
(1 -60). If you create menus for these utihties and save the input parameters, you 
must use the preassigned numbers on the &SAVEnn statements. See Figure 3-9 on 
page 3-15 for the numbers assigned to the EDX utilities. 
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An example of the statements for the combined $EDXASM/$UPDATE parameter 
input menu (Figure 3-8 on page 3-11) follows: 



PARAMETER 




&PARM01,&SAVE01 


(source input) 


&PARM02,&SAVE02,&SAVE19 


(object output) 


&PARM03,&SAVE03 


(compiler options) 


&PARM04,&SAVE20 


(pgm name) 


&PARM05,&SAVE21 


(replace?) 


&PARM06,&SAVE22 


(terminal) 


END 





You can determine which &SAVE statement the session manager assigns to a 
particular parameter input field by: 

1. Using $FSEDIT to hst the SSMPxxxx procedure for the utility. 

2. Comparing the &PARM and &SAVE statements from the hsting with the 
parameter input menu the session manager uses for that utihty. 

The procedure you write must pass parameters to each utility in the order shown in 
the $SMPxxxx procedure. 



4" 



o 
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The following figure shows the preassigned numbers for the EDX utilities: 



Statement 


Procedure 


Utility /Function 


&SAVE01-03 


$SMP0201 


$EDXASM 


&SAVE04-06 


$SMP0203 


$S1ASM 


&SAVE07-13 


$SMP0204 


SCOBOL 


&SAVE14-16 


$SMP0205 


$FORT 


&SAVE17-18 


$SMP0208 


SEDXLINK, 
SXPSLINK 


&SAVE19-22 


$SMP0209 


$UPDATE 


&SAVE23-24 


$SMP0211 


SPREFIND 


&SAVE25-26 


$SMP0308 


SMOVEVOL 


&SAVE27 


$SMP0405 


$FONT 


&SAVE28 


$SMP0501 


SDIUTIL 


&SAVE29 


$SMP0502 


$DICOMP 


&SAVE30 


$SMP0503 


SDIINTR 


«feSAVE31-35 


$SMP06 


Execute appHcation 
program 


&SAVE36 


$SMP0801 


$BSCTRCE, 
SLCCTRCE 


&SAVE37 


$SMP0806 


$PRT2780 


«feSAVE38 


$SMP0807 


$PRT3780 


&SAVE39 


$SMP0808 


SHCFUTl 


&SAVE40-41 


$SMP0211 


$PREFIND 


&SAVE42 


$SMP0207 


$EDXLINK 


&SAVE43 


$SMP0901 


$DUMP 


&SAVE44 


$SMP0208 


$XSPLINK 


&SAVE45-49 


$SMP0206 


$PLI 


«&SAVE45-50 


$SMP0212 


SPASCAL 


ifeSAVESl 


$SMP8101 


$ARJE 


&SAVE52-58 


$SMP0904 


SVERIFY 


&SAVE59 


$SMP0204 


SCOBOL 


&SAVE60 


Reserved 





Figure 3-9. &SAVEnn Numbers of EDX Utilities/Functions 



^^^k 
^^0^ 
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Writing the $JOBUTIL Control Statements 

The procedure you write must use $JOBUTIL control statements. The session 
manager passes the statements in this part of the procedure to SJOBUTIL, which 
then loads and executes the program. The Operator Commands and Utilities 
Reference describes the $JOBUTIL control statements in detail. 

This section shows three examples of $JOBUTIL control statements used in 
conjunction with &PARMnn statements. Use the examples presented as a guide as 
you write your procedure. The first example is the procedure required to load 
$EDXASM. The remaining examples show the procedures for the new options, 
PAYCHK and $EDXASM/$UPDATE. 

You must enter SJOBUTIL control statements in the following format: 
Command Position 1 to 8 
Operand Position 10 to 17 
Comment Position 18 to 71. 

Saving the Procedure 

After you enter the statements, do the following: 

1. Return to the $FSEDIT primary option menu by entering MENU on the 
command line. 

2. Select option 4 and specify the data set name for the new procedure. Specify 
EDX002 as the volume name. 

Procedure names can be a maximum of eight characters in length ($SMPxxxx) / ~~> 

and must have the prefix $SMP. The "xxxx" portion of the name should i^ J 

contain the numbers that reflect the option numbers on the primary option 
menu and the secondary option menu (if you use one). 

However, procedure names must correspond with the name of the parameter 
input menu. For example, you name the procedure for the PAYCHK program 
$SMP1102. This name corresponds to the name of the parameter input menu 
$SMM1102. Similarly, you name the procedure for the $EDXASM/$UPDATE 
option $SMP0215. This name corresponds to the parameter input menu 
$SMM0215. See the section "How to Name New Menus and Procedures" on 
page 3-1 for an explanation of how to name procedures. 

3. After you save the procedure, enter option 8 to exit $FSEDIT and return to the 
session manager. 

The next step is updating the session manager's primary and/or secondary procedure. 
The section "Updating the Primary Procedure" on page 3-19 explains how you can 
do this. 
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Examples of Procedures 

Use the examples shown in this section as a guide for the procedures you write. 

The session manager uses many different procedure formats. You can write more 
sophisticated procedures by copying existing session manager procedures and 
updating them. Use the $FSEDIT utility to change the procedures to call different 
programs and save parameters. 



$EDXASM Procedure 






PARAMETER 


&PARM01 


&SAVE01 (source input) 


&PARM02 


&SAVE02 (object output) 


&PARM03 


&SAV (compiler options) 


END 




LOG 


OFF 


REMARK 


(BASSEMBLE &PARM01. TO &PARM02. USERID=&PARMGO. 


JOB 


$SMP02O1 


PROGRAM 


$EDXASM,ASMLIB 


PARM 


&PARM03. 


DS 


&PARM01. 


DS 


$SM1&PARM00.,EDX003 (work data set) 


DS 


&PARM02. 


EXEC 




EOJ 




END 





Figure 3-10. Procedure to Load SEDXASM 



PAYCHK Procedure 



The system saves the parameters passed in &SAVE61 — &SAVE63. Figure 3-7 on 
page 3-9 shows the parameter input menu for this procedure. 






PARAMETER 




&PARM01 


&SAVE61 


(input data set) 


&PARM02 


&SAVE62 


(output data set) 


&PARM03 


&SAVE63 


(period end date) 


END 






LOG 


OFF 




REMARK 


laPAYROLL PAYCHECK 


PROCEDURE USERID=&PARMO0. 


JOB 


$SMP1102 




PROGRAM 


PAYCHK, MYVOL 




PARM 


&PARM03. 




DS 


&PARM01. 




DS 


&PARM02. 




EXEC 






EOJ 






END 







Figure 3-11. Procedure to Load PAYCHK 
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$EDXASM/$UPDATE Procedure 

This procedure combines the session manager procedure for SEDXASM and 
SUPDATE into one procedure. One statement saves &PARM02 in both &SAVE02 
and &SAVE19. Figure 3-8 on page 3-11 shows the parameter input menu for this 



proc- 



V/VJ-U-X V. 



PARAMETER 


&PARM01, 


&SAVE01 (source input) 


&PARM02. 


&SAVE02,&SAVE19 (object output) 


&PARM03, 


&SAVE03 (compiler options) 


&PARM04, 


&SAVE20 (pgm name) 


&PARM05, 


&SAVE21 (replace?) 


&PARM06, 


&SAVE22 (terminal) 


END 




LOG 


OFF 


REMARK 


(BASSEMBLE &PARM01. TO &PARM02. USERID=&PARMO0. 


JOB 


$SMP0215 


PROGRAM 


$EDXASM,ASMLIB 


PARM 


&PARM03. 


DS 


&PARM01. 


DS 


$SM1&PARMOO.,EDXO03 (work data set) 


DS 


&PARM02. 


EXEC 




JUMP 


EXIT,NE,-1 


REMARK 


eCREATE LOAD MODULE &PARM02. TO &PARM04. 


PROGRAM 


$UPDATE,EDX002 


PARM 


&PARM06. &PARM02. &PARM04. &PARM05. 


EXEC 




LABEL 


EXIT 


EOJ 




END 





^i._i) 



Figure 3-12. Procedure to Load $EDXASM/$UPDATE 
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Updating the Primary Procedure 



You must update the session manager primary procedure ($SMPPRIM) whenever 
you add an option to the primary option menu or to a secondary option menu. The 
primary procedure contains all option numbers as well as menu and program names 
associated with all options. 



This section explains how you can update the primary procedure for options you 
add. 

Perform the following steps to update the primary procedure ($SMPPRIM) for a 
new option: 

1 . Select option 1 (text editing) on the primary option menu and press the enter 
key. The next menu to appear on the terminal screen is the primary option 
menu for $FSEDIT. 

2. Select option 3 (read) and specify SSMPFRIM as the data set name. Specify 
EDX002 as the volume name. Press the enter key. 

3. After the utihty reads SSMPPRIM into your work data set, enter option 2 (edit) 
to update SSMPPRIM. 

Entering Changes to the Primary Procedure 

The option number you specify can be either a number or a letter. Follow the 
format of $SMPPRIM as you enter option numbers, program, and menu names. 



Program with No Parameters 

Assume the new option (1 1 — PAYROLL) on the primary option menu is a program 
that does not require parameters. (The program can be loaded directly). To update 
SSMPPRIM, scroll to the bottom (PF3 key) and add the new option number and 
program name. You would update SSMPPRIM to look like the following: 



'9 


,$SMM09 


'9.1 


,SSMM0901 


'9.2 


,*$DISKUT2EDXGQ2 


'9.3 


,*$I0TEST EDX002 


'9.4 


,$SMMO904 


'10 


,$SMM10 


■10.1 


,*$J0BQUT EDX002 


'10.2 


,*$SUBMIT EDX0Q2 


'11 


/PAYROLL EDX002 



DIAGNOSTICS SECONDARY OPTION MENU 
$DUMP PARM INPUT MENU 
EXECUTE $DISKUT2 
EXECUTE SIOTEST 
SVERIFY PARM INPUT MENU 
SJOBQUT/SSUBMIT OPTION MENU 
EXECUTE $JOBQUT 
EXECUTE SSUBMIT 
EXECUTE PAYROLL PROGRAM 



Figure 3-13. Example of a Program Added with No Parameters 

The asterisk before the program name indicates the program does not require 
parameters when loaded. 
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Optionally, you could pass a data set and volume name to a program. You might 
want to do this if your program normally prompts you for a data set after you load 
the program. For example, SFSEDIT and SEDXLINK prompt you for a work data 
set when you load them. You can pass your program one of the session manager 
work data sets or a data set you create. An asterisk must precede and follow the 
data set name (padded to eight characters in length). 

The following example shows how to use a session manager work data set: 
! '1 ',*$FSEDIT EDX0O2 *$SME& *EDX003 



$FSEDIT uses the session manager work data set SSMEuser, where "user" is your 
1 - 4 character logon ID. 

If you append an & to the data set name $SME, the session manager replaces the & 
with your logon ID. 

The next example shows how to pass a program the data set WORKDSl on volume 
MYVOL: 



',*$FSEDIT EDXO02*WORKDS1 *MYVOL 



At this point, you must save SSMPPRIM. See the section "Saving the Primary f^''~''\ 

Procedure" on page 3-23 for information on saving SSMPPRIM. After you save '\^ 

SSMPPRIM, you can use your new option from the primary option menu. 
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Program Using Parameter Input Menu Only 

If the new option (11 — PAYROLL) required only a parameter input menu, you 
would update $SMPPRIM as shown in Figure 3-14. In this case, scroll to the 
bottom (PF3 key) and add the new option number and the name of the parameter 
input menu. 

Note: The session manager searches for a procedure on EDX002 that corresponds 
to the name of the parameter input menu. For example, to load the program for 
$SMM1102, the session manager would search EDX002 for a procedure named 
$SMP1102. 



■9 


,$SMMG9 


'9.1 


,$SMM09O1 


'9.2 


.*$DISKUT2EDX0O2 


'9.3 


,*$IOTEST EDX0O2 


'9.4 


,$SMM0904 


■10 


,$SMM10 


■10.1 


,*$JOBQUT EDXO02 


'10.2 


,*$SUBMIT EDX002 


■11 


,$SMM1102 



DIAGNOSTICS SECONDARY OPTION MENU 
$DUMP FARM INPUT MENU 
EXECUTE $DISKUT2 
EXECUTE $IOTEST 
$VERIFY FARM INPUT MENU 
$JOBQUT/$SUBMIT OPTION MENU 
EXECUTE $JOBQUT 
EXECUTE $SUBMIT 
EXECUTE PAYROLL PROGRAM 



Figure 3-14. Example of a Program Added with Parameter Input Menu 

After you make the entry, you must save SSMPPRIM. See the section "Saving the 
Primary Procedure" on page 3-23 for information on saving $SMPPRIM. After 
you save SSMPPRIM, you can use your new option from the primary option menu. 
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Program Using Secondary Option Menu 

The PAYROLL example shown throughout this chapter is a new option on the 
primary option menu but also uses a secondary option menu. To update 
$SMPPRIM, scroll to the bottom (PF3 key) and make the entries as shown in 
Figure 3-15. An explanation of the entries follows the figure. 



f\ 



9 


,SSMM09 


9.1 


,$SMM0901 


9.2 


,*SDISKUT2EDXO02 


9.3 


,*$IOTEST EDX002 


9.4 


, $SMMO904 


10 


,$SMM10 


10.1 


,*$J0BQUT EDX002 


10.2. 


,*$SUBMIT EDX002 


11 


,$SMM11 


11.1 


,*MAILLISTMYVOL 


11.2 


,$SMM1102 



DIAGNOSTICS SECONDARY OPTION MENU 

$DUMP PARM INPUT MENU 

EXECUTE $DISKUT2 

EXECUTE SIOTEST 

SVERIFY PARM INPUT MENU 

SJOBQUT/SSUBMIT OPTION MENU 

EXECUTE $JOBQUT 

EXECUTE $SUBMIT 

PAYROLL SECONDARY OPTION MENU 

EXECUTE MAILING LIST PROGRAM 

PAYCHECK PARM INPUT MENU 



Figure 3-15. Example of Program AddeS Using Secondary Option Menu 

The entry for option 11 points to the secondary option menu $SMM11 (Figure 3-6 
on page 3-8). The entry for option 11.1 points to the program MAILLIST on 
volume MYVOL. MAILLIST requires no parameters when the session manager 
loads it. The entry for option 11.2 points to the parameter input menu $SMM1102 
(Figure 3-7 on page 3-9) for the PAYCHK program. 

Note; The session manager searches for a procedure on EDX002 that corresponds 
to the name of the parameter input menu. For example, to load the program for 
$SMM1102, the session manager would search EDX002 for a procedure named 
$SMP1102. 



y 
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You would perform similar update steps to add the $EDXASM/$UPDATE example 
discussed in "Adding an Option to a Secondary Option Menu" on page 3-5. For 
this example, you enter option number 2.15 and the menu name $SMM0215 as 
shown in Figure 3-16. 



'2.11 
'2.12 
'2.13 
'2.14 
'2.15 



,$SMM0211 $PREFIND PARM INPUT MENU 

,$SMM0212 $PASCAL/$EDXLINK PARM INPUT MENU 

,$SMM0213 $EDXASM/$XPSLINK PARM INPUT MENU 

,*$MSGUT1 EDX002*$SM1& *EDX003 

,$SMM0215 NEW $EDXASM/$UPDATE OPTION 



Figure 3-16. Example of Adding $EDXASM/$UPDATE Option 

At this point, you must save $SMPPRIM. See the section "Saving the Primary 
Procedure" for information on saving SSMPPRIM. After you save SSMPPRIM, 
you must update or create a secondary procedure. The section "Updating or 
Creating a Secondary Procedure" explains how to do this. 






Saving the Primary Procedure 

When you complete the updating of SSMPPRIM, do the following: 

1 . Enter MENU in the command field to return to the SFSEDIT menu. 

2. Select option 4 from the SFSEDIT primary option menu. Respond Y to the 
prompt message to write the updated procedure back to SSMPPRIM on volume 
EDX002. 

3. Enter option 8 to end SFSEDIT and return to the session manager primary 
option menu. 



Updating or Creating a Secondary Procedure 



You must update a secondary procedure whenever you add an option to an existing 
secondary option menu. Further, if you create a new secondary option menu you 
must create a secondary procedure for that option menu. 

The format of a secondary procedure is almost identical to the format of the primary 
procedure (SSMPPRIM). A secondary procedure contains option numbers and 
menu and program names that pertain only to a specific secondary option menu. 

All secondary procedures begin with the name SSMPxx, where xx is the number 
from the primary option menu. For example, $SMP04 is the secondary procedure 
for terminal utihties (option 4). 
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Updating an Existing Secondary Procedure 

The $EDXASM/$UPDATE example (Figure 3-5 on page 3-6) shows how to add an 
option to an existing secondary procedure ($SMP02). 

Perform the following steps to update $SMP02: 

1 . Select option i (text editing) on the primary option menu and press the enter 
key. The next menu to appear on the terminal screen is the primary option 
menu for SFSEDIT. 

2. Select option 3 (read) and and specify $SMP02 as the data set name. Specify 
EDX002 as the volume name. 

3. After the utility reads $SMP02 into your work data set, enter option 2 (edit) to 
update $SMP02. 

4. Scroll to the bottom (PF3 key) and enter the new option number and the name 
of the parameter input menu (Figure 3-8 on page 3-11). 

The following is an example of the updated $SMP02 procedure: 



SELECTION $SMP02 




^ 


'1 


',$SMM0201 


SEDXASM FARM INPUT MENU 




'2 


'.$SMM0202 


$EDXASM/$EDXLINK PARM INPUT MENU 




'3 


',$SMM0203 


$S1ASM PARM INPUT MENU 




'4 


',$SMM02O4 


$COBOL PARM INPUT MENU 




'5 


',$SMMO205 


$FORT PARM INPUT MENU 




"6 


',$SMM02O6 


$PLI/$EDXLINK PARM INPUT MENU 




'7 


',$SMM0207 


$EDXLINK PARM INPUT MENU 




'8 


' ,$SMM0208 


$XPSLINK FOR SUPERVISORS PARM INPUT MENU 




'9 


'.$SMM0209 


$UPDATE PARM INPUT MENU 




'10 


',*$UPDATEHEDX0O2 EXECUTE $UPDATEH 




'11 


',$SMM0211 


$PREFIND PARM INPUT MENU 




'12 


',$SMM0212 


$PASCAL/$EDXLINK PARM INPUT MENU 




'13 


',$SMM0213 


$EDXASM/$XPSLINK PARM INPUT MENU 




•14 


',*$MSGUT1 EDX 


302*$SM1& *EDX003 




'15 


',$SMM0215 


NEW $EDXASM/$UPDATE OPTION 




END 






J 



Figure 3-17. Updated $SMP02 Secondary Procedure 



Saving an Existing Secondary Procedure 

When you complete the updating of $SMP02: 

1. Enter MENU in the command field to return to the SFSEDIT menu. 

2. Select option 4 from the SFSEDIT primary option menu. Respond Y to the 
prompt message to write the updated procedure back to $SMP02 on volume 
EDX002. 

3. Enter option 8 to end SFSEDIT and return to the session manager primary 
option menu. 



After completing these steps, you can use the new option from either the primary or 
secondary option menu. 



C 
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Creating a Secondary Procedure 

To show you how to create a new secondary procedure, the PAYROLL example 
(Figure 3-6 on page 3-8) is used. 

A simple way to create a new secondary procedure is to edit an existing secondary 
procedure. You can add the appropriate entries you need for your program and 
delete the entries you do not need. By editing an existing secondary procedure, you 
can ensure that the required format remains correct. All existing secondary 
procedures are named $SMPxx, where xx is an option number. 

Perform the following steps to create a new secondary procedure: 

1 . Select option 1 (text editing) on the primary option menu and press the enter 
key. The next menu to appear on the terminal screen is the primary option 
menu for SFSEDIT. 

2. Select option 3 (read) and specify the data set name of an existing secondary 
procedure, for example $SMP02. Specify EDX002 as the volume name. 

3. After the utihty reads $SMP02 into your edit work data set, enter option 2 (edit) 
to edit $SMP02. 

4. Keeping the same format, replace the entries in $SMP02 with the entries for 
PAYROLL. 

The following is an example of the secondary procedure for PAYROLL: 



SELECTION. $SMP11 

'1 ',*MAILLIST MAILING LIST PROGRAM 
'2 ',$SMM1102 PAYCHK FARM INPUT MENU 
END 



Figure 3-18. New Secondary Procedure for PAYROLL 



Saving a New Secondary Procedure 

When you complete the updating, do the following: 

1 . Enter MENU in the command field to return to the $FSEDIT menu. 

2. Select option 4 from the $FSEDIT primary option menu. Specify the new data 
set name which will contain the secondary procedure. For this example, enter 
$SMP11 as the new data set name. SFSEDIT will create this data set for you. 
Specify EDX002 as the volume name. Respond Y to the prompt message after 
you specify the new data set name. 

3. Enter option 8 to end SFSEDIT and return to the session manager primary 
option menu. 

After completing these steps, you can use the new option from the primary option 
menu. 



o 
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Using an Alternate Session [\/lenu _^ 

When you log on to the session manager, you can override the menu presentation by \^ 

specifying an option menu that you have created. You might consider this method 
to provide menus tailored to your system. 

You can use the ALTERNATE SESSION MENU prompt below the user ID 
prompt if you create your own menus and procedures. Entering the name of your 
menu as an alternate causes your menu to appear instead of the session manager 
primary option menu. 

When you use this method of customizing the session manager: 

1 . Adhere to the naming conventions discussed in the section "How to Name New 
Menus and Procedures" on page 3-1. 

2. Ensure the menus and associated procedures reside on volume EDX002. 

3. Design the menus and procedures as discussed throughout this chapter. 

The following example shows the logon menu with the name of an alternate menu, 
$SM9901, specified: 



SSMMLOG: THIS TERMINAL IS LOGGED ON TO THE SESSION MANAGER | 

17:55:31 ! 

ENTER 1-4 CHAR USER ID ==> MYID 12/11/86 . 

(ENTER LOGOFF TO EXIT) 

1 

ALTERNATE SESSION MENU ==> $SM9901 j /^^, 

(OPTIONAL) ; \^y 



Figure 3-19. Session Manager Logon Screen with Alternate Menu 



How to iVIodify Data Set Allocation and Deletion 

The session manager allocates and deletes temporary data sets when you logon and 
logoff respectively. The session manager uses these data sets as work data sets for 
the various programs it loads. Two session manager data sets control allocation and 
deletion. SSMALLOC controls the data sets to be allocated. SSMDELET controls 
the data sets to be deleted. 

You can tailor the work data set allocations and deletions by modifying the 
SSMALLOC and SSMDELET data sets with SFSEDIT or SEDITIN. 
Modifications usually consist of changing the size or volume name of a data set. 
However, you can also allocate and delete up to four additional data sets. 

You can use these additional temporary data sets for programs you use. For 
example, your program may need to write data to a temporary data set and later 
retrieve data from that data set. You could run your program under the session 
manager and have the session manager create that data set. 
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Figure 3-20 lists all the session manager data sets with sizes and functions. The 
session manager substitutes your logon ID for "user" and appends your logon ID to 
the data set name. 






Data Set 
Name 


Size in 256 
EDX Records 


Function 


$SMEuser 


400 


Used by 'SFSEDIT as a work data 

set. 


SSMPuser 


30 


Used by session manager to save 
input parameters from session to 
session. This data set is not 
deleted at logoff. 


SSMWuser 


30 


Used by session manager to 
submit procedures to $JOBUTIL. 


SSMluser 


400 1 


Used by $S1ASM, SEDXASM, 
SCOBOL, SPASCAL, $PLI, and 
$FORT as a work data set. 


$SM2user 


400 1 


Used by SEDXLINK, $S1ASM, 
SCOBOL, $PLI, and $FORT as a 
work data set. 


$SM3user 


250 1 


Used by $S1ASM, SCOBOL, 
SPASCAL, and $PLI as a work 
data set. 



Figure 3-20. Data Sets Created by the Session Manager 

Note: When using the background option, data sets SSMluser, $SM2user, and 
$SM3user are reserved for use by the session manager. The session manager 
allocates one additional work data set (SSMBJOBQ) for the entire system to use for 
background processing. Every job submitted in background that needs a work data 
set will use this preallocated data set. If you never intend to run background jobs, 
your system manager can move the entry (SSMBJOBQ) after the end statement in 
the data set SSMALLOC. 



1 Using the assemblers and compilers noted may require that you delete and reallocate 
these data sets to a larger size. Recommended sizes are 2000 for both $SM1 and $SM2, 
and 800 for $SM3. During system generation, you may have to increase the size of 
SSMluser to 800 records. 
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Aliocating Data Sets 

In addition to allocating data sets $SM1 through $SM3, you can allocate data sets 
$SM4 through $SM7. The default size of these data sets is 100 records. 

The following is an example of how SSMALLOC looks: 



$SMP 


00 


EDX003 


$SMP 


30 


EDXO03 


$SMW 


30 


EDXO03 


$SME 


400 


EDX0O3 


$SM1 


400 


EDX003 


$SM2 


400 


EDX003 


$SM3 


400 


EDX003 


END 


*** TERMINATOR - 


$SM4 


100 


EDX003 


$SM5 


100 


EDX0O3 


$SM6 


100 


EDX0O3 



NAME AND VOLUME FOR OPEN 

SIZE AND VOLUME TO ALLOCATE 

SIZE AND VOLUME TO ALLOCATE 

SIZE AND VOLUME TO ALLOCATE 

SIZE AND VOLUME TO ALLOCATE 

SIZE AND VOLUME TO ALLOCATE 

SIZE AND VOLUME TO ALLOCATE 

INDICATES END OF ALLOCATED DATA SETS *** 

SIZE AND VOLUME TO ALLOCATE 

SIZE AND VOLUME TO ALLOCATE 

SIZE AND VOLUME TO ALLOCATE 

$SM7 100 EDX003 SIZE AND VOLUME TO ALLOCATE 
*********************************************************************** 

*********************************************************************** 

** $SML06 WORK DATA SET PARAMETER VALUES FOR ALLOCATE FUNCTION ** 

** NOTE: THE DATA SETS $SMW AND $SMP MUST RESIDE ON ** 

** THE VOLUME EDX0O3. ALL OTHERS MAY BE REASSIGNED ** 

** NOTE: THE FIRST ENTRY IN THIS LIST IS USED TO TEST FOR ** 

** THE EXISTENCE OF THE $SMP DATA SET. DON'T DELETE. 

** COPYRIGHT = REFER TO MODULE $$COPYRT 

*********************************************************************** 

*********************************************************************** 



** 
** 



END 



*********************************************************************** 



\^ 



Figure 3-21. $SM ALLOC Data Set 

If you want $SM4 allocated, move the END statement (in column 1) to follow 
$SM4. The END statement indicates the end of the list of data sets to be allocated. 
If you add data sets to the list in $SM ALLOC, you should also add names of the 
data sets to SSMDELET. If you change the volume name of a work data set in the 
SSMALLOC and SSMDELET data sets, then you have to change all the session 
manager procedures that use that work data set. After you complete your 
modifications, you must save the updated SSMALLOC data set. 

The only required data sets are $SMP and $SMW. You must allocate these data 
sets on volume EDX003. 



r\ 
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Deleting Data Sets 

Before you end the session manager, the session manager prompts you for the 
disposition of the data sets. The data sets you allocated at the start of the session 
are usually deleted before you end the session manager. Enter a Y to save the data 
sets or an N to delete the data sets. 

Note: Abnormal termination of the session manager prevents the deletion of the 
temporary data sets. 

If you add data set names in SSMALLOC, you must also update $SMDELET with 
those data set names. Update SSMDELET in a similar manner to SSMALLOC. 
The END statement (in column 1) indicates the last data set to be deleted. After 
you complete your modifications, you must save the updated SSMDELET data set. 

Figure 3-22 lists the contents of SSMDELET. 






NAME AND VOLUME TO DELETE 

NAME AND VOLUME TO DELETE 

NAME AND VOLUME TO DELETE 

NAME AND VOLUME TO DELETE 

NAME AND VOLUME TO DELETE 

END OF DATA SETS TO BE DELETED *** 

NAME AND VOLUME TO DELETE 

NAME AND VOLUME TO DELETE 

NAME AND VOLUME TO DELETE 

$SM7 EDX003 PREFIX NAME AND VOLUME TO DELETE 

*************************************************************** 

*************************************************************** 

** $SMEND WORK DATASET PARAMETER VALUES FOR DELETE FUNCTION ** 

** COPYRIGHT = REFER TO MODULE $$COPYRT ** 

*************************************************************** 

*************************************************************** 

END 

*************************************************************** 



$SME 


EDXO03 


PREFIX 


$SM1 


E0X003 


PREFIX 


$SM2 


EDX003 


PREFIX 


$SM3 


EDX0O3 


PREFIX 


$SMW 


EDXO03 


PREFIX 


END 


*** TERMINATOR - 


INDICATES 


$SM4 


EDX003 


PREFIX 


$SM5 


EDX0O3 


PREFIX 


$SM6 


EDXO03 


PREFIX 



Figure 3-22. SSMDELET Data Set 
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Chapter 4. Adding Your Own Task Error Exit Routine 

When a program is executing, an exception condition may occur either in the 
program itself or in the Series/ 1 processor. If an exception occurs, the supervisor 
calls the error handling routine, displays diagnostic information in the form of a 
program check message on SSYSLOG, and cancels the program. You can provide 
your own exception handhng routine by writing a task error exit routine. 

When you provide a task error exit routine in your program, the supervisor passes 
control to your EDL routine when an exception occurs. Then your routine can 
capture and format status information specific to your program. 

Some of the processing your task error exit routine could perform is: 

• Releasing any enqueued resources such as event control blocks (ECBs) or queue 
control blocks (QCBs). 

• Displaying, on all terminals currently being used by the program, a message that 
would inform the operator(s) of a malfunction and the appropriate action to 
take. 

• Printing the data set control blocks (DSCBs) from the program header and the 
program. 

• Printing the input/output control blocks (lOCBs), terminal control blocks 
(CCBs), and task control blocks (TCBs) in your appHcation. 

• Printing any sensor-based I/O control blocks (SBIOCBs) or any other data 
special to your appHcation. 

• Reloading your program or loading another program. 

You can: 

• Extend the system-supphed task error exit routine ($$EDXIT). 

• Provide your own routine independent of $$EDXIT. 

You specify the EDL entry point name of the task error exit routine on the 
ERRXIT= operand of the PROGRAM or TASK statement. 

The following sections describe how to extend the system-supphed task error exit 
routine or create your own task error exit routine. 
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Extending the System-Supplied Task Error Exit Routine 

The system-supplied task error exit routine ($$EDXIT) prints and displays general 
information regarding an exception check. Figure 4-1 shows an example of the 
output. The Problem Determination Guide discusses this exception output in detail. 



****************************************** 




* WARNING!! AN EXCEPTION 


HAS 


OCCURRED!! * 




****************************************** 




PROGRAM NAME 


PCHECK 




PSW = 8002 




PROGRAM VOLUME 


EDXWRK 




lAR = 2AD6 




PROGRAM LOAD POINT 


0000 




AKR = 0110 




ADDRESS OF ACTIVE TCB 


0120 




LSR = 8OD0 




ADDRESS OF CCB 


0F5E 




RO (WORK REGISTER) 


= 0064 


NUMBER OF DATA SETS 


1 




Rl (EDL INSTR ADDR) 


= 01OA 


NUMBER OF OVERLAYS 







R2 (EDL TCB ADDR) 


= 0120 


$TCBADS 


0001 




R3 (EDL OPl ADDR) 


= 0037 


ADDRESS OF FAILURE 






R4 (EDL 0P2 ADDR) 


= 0034 


(REL.TO PGM LOAD POINT) = 


010A 




R5 (EDL COMMAND) 


= 015C 


DUMP OF FAIL ADDRESS 






R6 (WORK REGISTER) 


= 0000 


O10A: 015C 0000 0034 8332 






R7 (WORK REGISTER) 


= 0000 


$TCBCO = -1 DEC; FFFF HEX 




#1 = 0037 




$TCBC02 = DEC; 0000 HEX 




#2 = 0000 




PSW ANALYSI$: 










SPECIFICATION CHECK 










TRANSLATOR ENABLED 














Figure 4-1. Sample Output from $$EDXIT 



o 
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How to Code the Task Error Exit Extension 

$$EDXIT contains a WXTRN statement for a routine called PCHKRTN. If 
PCHKRTN exists, $$EDXIT passes control to PCHKRTN after printing the 
exception check data on $SYSPRTR. Use PCHKRTN as the extension to 
$$EDXIT. 

To provide your routine as an extension to $$EDXIT, you must: 

• Specify MAIN = NO on the PROGRAM statement of your routine. 

• Code an ENTRY statement specifying PCHKRTN. 

• Specify PCHKRTN as the label of your routine. The executable code you 
provide begins at this label. 

• Specify a PROGSTOP statement following the executable code. 

• Specify the END statement as the last statement of your routine. 

For example: 



ERRRTN 


PROGRAM 


MAIN=NO 




ENTRY 


PCHKRTN 


PCHKRTN 


EQU 


* 




• 


(source code for your routine) 




PROGSTOP 






END 





Link Editing the Task Error Exit Extension 

After you assemble your routine, link edit the assembled output with your main 
program and $$EDXIT. The system includes $$EDXIT in the Unk edit when you 
specify an AUTOCALL statement referencing $AUTO,ASMLIB. The following is 
an example of the link control statements you pass to SEDXLINK. 



INCLUDE MAINOBJ.MYVOL 

AUTOCALL $AUTO,ASMLIB 

INCLUDE PCHKOBJ,MYVOL 

LINK MAINPGM,MYVOL REPLACE END 



(includes main pgm) 
(includes $$EDXIT) 
(includes your routine) 
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Creating Your Own Task Error Exit Routine 

This section explains how you can create your task error exit routine. A sample 
program is also shown to assist you in coding the routine. 

Defining the Task Error Exit Control Block 

When you create your own task error exit routine, you must define an area of 
storage called a task error exit control block (TEECB). The TEECB provides the 
linkage between the supervisor and your routine. The supervisor stores hardware 
status information in the TEECB when an exception occurs. You must define the 
TEECB area even if your routine does not use the status information. 

You must align the TEECB on a fullword boundary. The TEECB has the following 
format: 





ALIGN 


WORD 


ALIGN ON FULLWORD BOUNDARY 


TEECB 


EQU 


* 




TEECTL 


DC 


X'0002' 


CONTROL WORD 


TEESIA 


DC 


A(EXITRTN) 


ADDRESS OF STARTING INSTRUCTION 


TEEHSA 


DC 


A(HSA) 


ADDRESS OF HARDWARE STATUS AREA 



Figure 4-2. Format of the Task Error Exit Control Block (TEECB) 



In the first word (TEECTL), bits 0- 7 are reserved and must be zero. Bits 8-15 
specify the number of data words that follow. Always code X ' 0002 ' as the value of 
this word. 



The second word (TEESIA) contains the starting instruction address (SIA) of your 
task error exit routine. 

The last word (TEEHSA) contains the address of a storage area you reserve to 
receive the hardware status information. This storage area, called the hardware 
status area (HSA), is 24 bytes in length. 

You must align the HSA on a fullword boundary. The HSA has the following 
format: 





ALIGN 


WORD 


ALIGN ON FULLWORD BOUNDARY 


HSA 


EQU 


* 




HSAPSW 


DC 


F'O' 


PROGRAM STATUS WORD 


HSALSB 


EQU 


* 


11 WORD LEVEL STATUS BLOCK 


HSAIAR 


DC 


F'O' 


INSTRUCTION ADDRESS REGISTER 


HSAAKR 


DC 


F'O' 


ADDRESS KEY REGISTER 


HSALSR 


DC 


F'O' 


LEVEL STATUS REGISTER 


HSAREGS 


DC 


8F'0' 


GENERAL REGISTERS 0-7 



Figure 4-3. Format of the Hardware Status Area (HSA) 






4-4 SC34-0942 



Adding Your Own Task Error Exit Routine 






The contents of the various HSA locations (for example PSW and AKR) contain, 
upon entry to your routine, the values that were in the corresponding hardware 
registers at the time of the exception. Also, general register 1 contains the starting 
instruction address (SIA) of your routine. General register 2 contains the address of 
your task's TCB. Your routine can examine this status information to determine 
whether to continue or end execution. The Problem Determination Guide can assist 
you in interpreting the information returned from an exception. 



Since entry to your routine is made at the Event Driven Language level, the contents 
of the remaining general registers are dependent upon what instructions your 
program executed when the exception occurred. 

Sample Task Error Exit Routine 

An example of a task error exit routine follows. The sample program examines the 
processor status word (PSW) for the type of exception and displays the contents of 
some selected fields upon the loading terminal. 



^^*\ 

^k^ 





PRINT 


OFF 






COPY 


PROGEQU 






PRINT 


ON 






ENTRY 


TSKEXIT 




ERRXT 


PROGRAM 


MAIN=NO 




TSKEXIT 


EQU 


* 






ALIGN 


WORD 




TEECB 


EQU 


* 


TASK ERROR EXIT CONTROL BLOCK 


TEECTL 


DC 


X'0002' 


NUMBER OF DATA WORDS IN TEECB 


TEESIA 


DC 


A(EXITRTN) 


ADDRESS OF ERROR EXIT ROUTINE 


TEEHSA 


DC 


A(HSA) 


ADDRESS OF HARDWARE STATUS AREA 




ALIGN 


WORD 




HSA 


EQU 


* 


HARDWARE STATUS AREA 


HSAPSW 


DC 


F'O' 


PROGRAM STATUS WORD 


HSALSB 


EQU 


* 


11 WORD LEVEL STATUS BLOCK 


HSAIAR 


DC 


F'O" 


INSTRUCTION ADDRESS REGISTER 


HSAAKR 


DC 


F'O' 


ADDRESS KEY REGISTER 


HSALSR 


DC 


F'O' 


LEVEL STATUS REGISTER 


HSAREGS 


DC 


8F'0' 


GENERAL REGISTERS 0-7 


PCHKPLP 


DATA 


F'O' 


PGM LOAD POINT 


FAILADDR 


DATA 


F'O' 


FAILING ADDR 


ADDRTBL 


EQU 


* 






DC 


A(BIT0) 






DC 


A(BITl) 






DC 


A(BIT2) 






DC 


A(BIT3) 






DC 


A(BIT4) 






DC 


A(BIT5) 






DC 


A(BIT6) 






DC 


A(BIT7) 





Figure 4-4 (Part 1 of 2). Sample Task Error Exit Routine 
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DC 


A(BIT8) 






DC 


A(BIT9) 






DC 


A(BIT10) 






DC 


A(BITll) 






DC 


A(BIT12) 






DC 


A(BIT13) 






DC 


A(BIT14) 






DC 


A(BIT15) 




PSWTBL 


EQU 


* 




BITO 


TEXT 


'SPECIFICATION CHECK' 




BITl 


TEXT 


'INVALID STORAGE ADDRESS' 




BIT2 


TEXT 


'PRIVILEGE VIOLATE' 




BIT3 


TEXT 


'PROTECT CHECK' 




BIT4 


TEXT 


'INVALID FUNCTION' 




BITS 


TEXT 


'FLOATING POINT EXCEPTION 


1 


BIT6 


TEXT 


'STACK EXCEPTION' 




BIT7 


TEXT 


'EXTENDED ARCHITECTURE' 




BITS 


TEXT 


'STORAGE PARITY CHECK' 




BIT9 


TEXT 


'BIT 9 NOT USED' 




BIT10 


TEXT 


'CPU CONTROL CHECK' 




BITll 


TEXT 


'I/O CHECK' 




BIT12 


TEXT 


'SEQUENCE INDICATOR' 




BIT13 


TEXT 


'AUTO I PL' 




BIT14 


TEXT 


'TRANSLATOR ENABLED' 




BIT15 


TEXT 


'POWER/THERMAL WARNING' 




BITCNT 


DATA 


F'O" 




PSWORK 


DATA 


F'O' 




MSGREC 


TEXT 


LEN6TH=80 




EXITRTN 


EQU 


* 






TCBGET 


PCHKPLP,$TCBPLP 


GET PGM LOAD PT 




SUBTRACT 


HSAREGS+2 , PCHKPLP , RESULT= 


FAILADDR FAIL ADDR 




MOVE 


#1,PCHKPLP 






PRINTEXT 


'^PROGRAM NAME = ' 






PRINTEXT 


($PRGNAM,#1) 


PRINT PGM NAME 




PRINTEXT 


■@PSW = ' 






PRINTNUM 


HSA,MODE=HEX 


PRINT HSA VALUE 




PRINTEXT 


'@IAR = ' 






PRINTNUM 


HSA+2,M0DE=HEX 


PRINT INST ADDR REG 




PRINTEXT 


'0PSW ANALYSIS: (?' 






MOVE 


PSWORK, HSAPSW 






MOVE A 


#1,ADDRTBL 


MOVE MSG LIST ADDR 




DO 


16, TIMES, INDEX=BITCNT 






IF 


(BITCNT, GT,1) 






SHIFTL 


HSAPSW,! 






ENDIF 








IF 


(HSAPSW, LT,0) 






MOVE 


PSWMSG,(0,#1) 


POINT TO ERR MSG 




PRINTEXT 


MSGREC, P1=PSWMSG, SKI P=l 






ENDIF 








ADD 


#1,2 


INCREMENT INDEX 




ENDDO 








PROGSTOP 








END 







\^J 



Figure 4-4 (Part 2 of 2). Sample Task Error Exit Routine 
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You must compile the task error exit routine and link edit the assembled output with 
the main task. Specify the entry point name of the routine on the ERRXIT = 
operand of the main task. 

An example of the main task that specifies the previous routine follows: 



MA IN PGM 


PROGRAM 


START, ERRXIT=TSKEXIT 




EXTRN 


TSKEXIT 


START 


EQU 

• 

• 

• 

PROGSTOP 

ENDPROG 

END 


* 



Considerations on the Use of Tasic Error Exit Routines 

You should understand the following items when you use a task error exit routine: 

• A task error exit routine is a part of the task it serves. The supervisor passes 
control to it at the task level; it is not a subroutine of the supervisor's error 
handler. 

• If your main program attaches multiple tasks, you should specify the ERRXIT = 
operand on each TASK statement. 

• The registers (including the EDL software registers #1 and #2) used by the error 
exit routine are those normally used by the task. 

• To resume task execution after the task error exit routine, you must issue a 
branch instruction (for Series/ 1 assembler) or a GOTO instruction (for EDL) to 
the appropriate location. 

• If the task error exit routine is unable to recover from the exception, it should 
issue a PROGSTOP instruction. 
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What Happens When an Exception Occurs? 



If an exception (machine check, program check, or soft exception trap) occurs during 
the execution of your task and you have specified a task error exit, the supervisor 
locates your TEECB. It then uses the TEEHSA pointer to locate your HSA and 
stores the hardware status information in it. Next, the supervisor retrieves the 
TEESIA pointer and sets it to zero to prevent recursive exceptions. Finally, the 
supervisor starts your task at the address it retrieved if that address is nonzero. If 
the TEESIA is zero or an exception occurs during any of this processing (if, for 
example, the TEECB is invalid), the supervisor treats the error as if you did not 
specify a task error exit routine. Note that even if the TEESIA is zero, the 
supervisor still attempts to store the hardware status. 

Since the supervisor sets the TEESIA to zero prior to starting your task, your task 
error exit routine only gets control on the first exception that occurs, unless your 
routine restores TEESIA to its original condition. Setting TEESIA to zero allows 
the supervisor to handle exceptions that occur in task error exit routines, preventing 
recursion in the error handUng process. When you write a task error exit routine, do 
not restore TEESIA until the error exit routine has completed. 



W^^ 



V M 
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Chapter 5. Running Programs and Initialization Routines at 
IPL 

You can design your system so that your programs and initialization routines are 
run as part of the IPL process. You can do this by: 

• Naming your program $INITIAL 

• Creating a program named $PROGl linked with the supervisor 

• Coding the INITMOD operand on the SYSPARMS statement. 

Using SINITIAL to run programs at IPL is the simplest method. You can load 
$INITIAL by using the INITPRT operand of the SYSPARMS statement. 
Programs loaded through this method do not require link editing with the 
supervisor. As a result, the programs loaded can reside on disk. 

When you use $PROGl or specify initialization routines on the INITMOD operand, 
you must hnk edit these routines to the supervisor during system generation. 

The programs or routines that run could perform various functions. For example, 
using SINITIAL, you could have the session manager loaded in a particular 
partition and printer spoohng in another. 

Assume your Series/1 has no disk/diskette but communicates with a host over a BSC 
hne. The host could IPL the Series/ 1 by transmitting the supervisor (with SPROGl). 
SPROGl would run after IPL. 

If you always run a program that sets up an area of storage to some value, you 
could specify this program as an initialization routine. You do this by coding the 
INITMOD operand on the SYSPARMS statement. 

This chapter describes how you can supply programs and routines to be run at IPL 
using either of these methods. 



How to Specify $INITIAL Programs 






To have your programs loaded at IPL, you must name a program $INITIAL. Two 
ways you can assign the name SINITIAL to a program are as follows: 

• Using SDISKUTl to rename (RE command) an existing program. 

• Specifying the name SINITIAL as your program name when you prepare the 
program using SUPDATE or SEDXLINK. 

The SINITIAL program must reside on the IPL volume. 

Your SINITIAL program can issue LOAD instructions to other programs. You 
have complete control of the function performed by this program. 

After all system and user-written initialization routines execute, the supervisor issues 
a LOAD instruction for SINITIAL. 
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Things You Should Know About $INITIAL 

Effectively, you can use any program as a $INITIAL program. However, consider 
the follow^ing when you create a $INITIAL program: 

• You cannot use the "??" option to specify data sets (DS = ) or overlays 
(PGMS = ) on the PROGRAM statement. 

• No "program load" message is displayed when SINITIAL is loaded. 

• Any errors that occur when SINITIAL is loaded are not displayed; you should 
check all return codes. 

• If you want to prevent the supervisor from loading SINITIAL, rename the 
program using SDISKUTl. 

• You can use the INITPRT operand of the SYSPARMS statement to specify the 
partition into which SINITIAL is loaded. 

• You can code the PARM = operand on the PROGRAM statement to receive a 
parameter at load time. The system passes a 1-word parameter that indicates 
the type of IPL — manual or auto. 



Sample $INITIAL Programs 

The following examples show some of the functions you could use for SINITIAL. 

Loading Programs in Tliree Partitions 

The following sample program loads three programs. The session manager is loaded 
in partition 1, printer spoohng in partition 2, and Indexed Access Method in 
partition 3. The return code is checked for load errors. 



INIT 


PROGRAM 


LOADPGM 


LOADPGM 


EQU 


* 


LI 


LOAD 


$SMMAI N , PART=1 , ERROR=NOSMGR 


L2 


LOAD 


$SPOOL, PART=2 , ERROR=NOSPL 


L3 


LOAD 


$IAM,PART=3,ERR0R=N0IAM 




GOTO 


ALLDONE 


N0SM6R 


MOVE 


RCODE, INIT 




PRINTEXT 


'@LOAD ERROR FOR $SMMAIN, RC= ' 




PRINTNUM 


RCODE 




GOTO 


L2 NEXT LOAD 


NOSPL 


MOVE 


RCODE, INIT 




PRINTEXT 


'©LOAD ERROR FOR $SPOOL, RC= ' 




PRINTNUM 


RCODE 




GOTO 


L3 NEXT LOAD 


NO I AM 


MOVE 


RCODE, INIT 




PRINTEXT 


'©LOAD ERROR FOR $IAM, RC= ' 




PRINTNUM 


RCODE 


ALLDONE 


PROGSTOP 




RCODE 


DATA 

ENDPROG 

END 


F'O' 
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Determining tlie Type of IPL 

The following sample code shows how you can determine the type of IPL based on 
the IPL Mode switch setting. The system passes the parameter upon IPL. Your 
SINITIAL program could decide what routine to use based on the parameter value. 
A zero indicates manual IPL; a one indicates auto IPL. You must code the PARM 
operand on the PROGRAM statement to receive this parameter. Your program 
must refer to this parameter as $P ARM 1 . 



If, for example, your system had an external battery-operated clock (connected 
through a digital input feature) or kept the date and time on a disk data set, the 
program could read the time and date upon an auto IPL. SINITIAL could then 
load the time and date into the system time and date table (STIMRTBL). 



The following example shows how you could read the time and date from disk, 
time is set to 13:24:05 and the date to December 25, 1987. 



The 






INIT 


PROGRAM 


START, PARM=1,DS=((TIMDAT,MYV0L)) 




COPY 


PROGEQU RESOLVE $TIMRTBL REFERENCE 


START 


EQU 


* 




IF 


($PARM1,EQ,1), GOTO, AUTOIPL 


MAN I PL 


PRINTEXT 


■eMANUAL IPL DONE...' 




• 




(routine for manual IPL) 




GOTO 


EXIT 


AUTOIPL 


EQU 


* 




PRINTEXT 


'@AUTO IPL DONE...' 




READ 

• 


DSl, TIMRDATA READ TIME/DATE FROM DISK 




• 
MOVE 


#1,$TIMRTBL,FKEY=0 




MOVE 

• 


(8, #1), TIMRDATA, 6, TKEY=0 LOAD TIME/DATE 


EXIT 


• 
PROGSTOP 




TIMRDATA 


DC 


X'OOOD' HOUR 




DC 


X'0O18' MINUTE 




DC 


X'0005' SECOND 




DC 


X'OOOC MONTH 




DC 


X'0019' DAY 




DC 


X'O057' YEAR 




ENDPROG 






END 








Notes: 

1. Under SEDXASM, you must include a COPY PROGEQU statement to resolve 
the reference to STIMRTBL. 

2. TIMRDATA is a 6-word table containing the time and date in hexadecimal. 
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How to Use $PR0G1 at IPL 



You can have an application program run at IPL by link editing it with the 
supervisor. Doing this makes your program always resident in storage. Using 
$PROGl could be useful if your system does not have a disk or diskette device from 
which to load programs. 

After all system and user-written initiahzation routines execute, the supervisor issues 
an ATTACH for a SPROGl. 

To use $PROGl, you must code the program as follows. The program must contain 
a CSECT statement with a label name of $PROGl. 



$PR0G1 CSECT 



(source code) 



PROGSTOP 

ENDPROG 

END 



Link Editing $PR0G1 with the Supervisor 

After you assemble your program, you must link edit the assembled output with the 
supervisor. If you performed a tailored system generation, edit the data set that 
defines the supervisor modules currently in your supervisor (normally LINKCNTL 
on EDX002). Otherwise, you edit $UNKCNTL. An INCLUDE statement for 
SPROGl on volume XS6005 exists in the hnk-control data set. You must blank out 
the asterisk preceding the INCLUDE statement and indicate on which volume your 
$PROGl resides. 






An example of the hnk-control data set with an INCLUDE statement for SPROGl 
(on volume USRVOL) follows: 



******************************************************************* 

* SYSTEM INITIALIZATION - MUST BE IN PARTITION 1 * 

******************************************************************* 



INCLUDE $PR0G1, USRVOL 
*INCLUDE 101024 



1(22* 

lr21* 



USER MODULE INCLUDED IN NUCLEUS GEN 
1024 IPL SUPPORT 



%. w 
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After changing the INCLUDE statement, save the edited data set in LINKCNTL on 
EDX002. Next, you load SJOBUTIL and specify SUPPREPS when prompted for a 
data set. SUPPREPS will generate a new supervisor containing your $PROGl 
program. 

After you receive a — 1 completion code, load SINITDSK and issue the II command 
to point to the new supervisor. IPL the new supervisor. 

What Happens When $PR0G1 Executes? 

When the supervisor attaches $PROGl, all of the storage in partition 1 is assigned 
to SPROGl. If you issue the $A operator command, the system will show $PROGl 
in storage. Because all of partition 1 is assigned to $PROGl, you cannot load any 
other programs until $PROGl issues a PROGSTOP. 



How to Specify Initialization Routines 






You can supply initialization routines that are run as part of the IPL. These 
routines are called after the system initialization routines execute. This section 
describes how you can do this. 

Designing and Coding the Routine 

The routine you supply can be written in EDL or Series/ 1 assembler. However, the 
first instruction of the routine must be an EDL instruction. You must also consider 
the following: 

• The routine must be written to receive and return control in EDL. 

• You must use the USER instruction to switch from EDL to assembler. 

• You must preserve the contents of register 2. 

• You must preserve the task control block (TCB) pointer. 

• LOAD and PROGSTOP instructions are not allowed. 

• Upon exit, the routine must return control to the label INITEXIT. INITEXIT 
is an entry point in the supervisor. 

The following coding examples show how you should code your routine. The first 
example uses EDL only; the second uses EDL and Series/ 1 assembler. 



Routine using EDL 






INITRTN 


PROGRAM 


MAIN=NO 




EXTRN 


INITEXIT 




ENTRY 


INIT 


INIT 


EQU 


* 




• (EDL code) 




GOTO 


INITEXIT 
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Routine using EDL and Series/1 Assembler 



INITRTN 


CSECT 








EXTRN 


INITEXIT 






USER 


INIT 




INIT 


EQU 


* 






• 


(assembler code) 






MVA 


INITEXIT, Rl 






BX 


CMDSETUP 


BACK TO EDL 



Link Editing the Routine with the Supervisor 

After you assemble your routine, you must link edit the assembled output with the 
supervisor. If you performed a tailored system generation, edit the data set that 
defines the supervisor modules currently in your supervisor (normally LINKCNTL 
on EDX002). Otherwise, you edit SLNKCNTL. Insert an INCLUDE statement 
specifying the name of the assembled output in the area designated for user 
initialization modules. For example, if your assembled output module is named 
INITOBJ on volume MYVOL, the INCLUDE statement would be as follows: 



******************************************************************** 

* INSERT USER INITIALIZATION MODULES HERE * 

******************************************************************** 



INCLUDE INITOBJ, MYVOL 



YOUR NEW INIT ROUTINE 



Vy 



After inserting the new INCLUDE statement, save the edited data set in 
LINKCNTL on EDX002. Optionally, you can include the initialization routine as 
an overlay to save storage. The Installation and System Generation Guide describes 
how to specify and use the overlay feature. If you do not use the overlay feature, go 
to the section "Specifying the Routine on the SYSPARMS Statement" on page 5-7. 
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Specifying the Routine on the SYSPARIVIS Statement 

You must edit the data set which defines your system to specify the routine. This 
data set is normally SEDXDEFS on volume EDX002. Code the INITMOD 
operand on the SYSPARMS statement to specify the entry point name of your 
routine. You can specify one or more routines. If you do, specify each entry-point 
name separated by a comma and enclose the name Hst in parentheses. The routines 
are executed in the order you specify. 



An example of the SYSPARMS statement with the INITMOD operand coded 
follows. Two initialization routines are specified. 



SYSPARMS INITMOD=(INIT,RTNA) 



After you edit and save SEDXDEFS, load SJOBUTIL and specify SUPPREPS when 
prompted for a data set. SUPPREPS will generate a new supervisor containing your 
initialization routine. 



Upon receiving a — 1 completion code, load $INITDSK and issue the II command 
to point to the new supervisor. IPL the new supervisor. 
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Chapter 6. Adding Your Own Device Support 

If you have a need to use a device or device feature not supported under EDX, you 
can provide support for that device or feature through the use of EXIO. The 
system's EXIO support enables you to control, from your programs, any device that 
meets the hardware channel architecture (such as plug compatibility and device 
control blocks) of the Series/1. These devices can be IBM or original equipment 
manufacturer (OEM) devices. 

This chapter describes how you can provide your own device support using EXIO. 
In addition, a sample program using EXIO is shown. The sample program 
illustrates an approach you could use to support a device attached to the 2095/2096 
Feature Programmable Multiline Controller/ Adapter using expanded mode (with 
continuous receive) and one stop bit. 



How You Can Use EXIO 

The system's EXIO support enables you to perform I/O-level programming for a 
device attached to the Series/ 1. Furthermore, with EXIO, you can do the following: 

• Gain closer control of an EDX-supported device. With EXIO, you control 
every aspect of the device's operation. For example, you can provide a more 
extensive error-handling and error-recovery procedure than EDX provides for 
that device. 

• Issue I/O from a program in any partition. 

• Provide support for a device without adding any new supervisor code. The 
device support resides in your program. 

• Write the support as reentrant code or as subroutines you hnk to each program 
using the device(s). (Refer to the Event Driven Executive Language Programming 
Guide for a reentrant coding example.) 

• Provide I/O level programming in EDL without using Series/ 1 assembler. 
However, some device operations may require the speed of execution that 
Series/ 1 assembler provides. You can mix the two languages and assemble with 
SSIASM. 

The next section discusses several considerations you need to think about before you 
implement the device support. The topics presented can assist you when you 
actually start writing the device support code. 



Planning for Your Device Support 






Because you must control every operation the device performs when you use EXIO, 
you must be famihar with the device you intend to support. The IBM Series/ 1 
Principles of Operation, GA34-0152 presents a general overview of the Series/ 1 I/O 
architecture. 

The following topics describe some of the device requirements with which you should 
be familiar. 
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Do You Understand the Hardware Control Block Functions? 

To properly control the device, you must understand the function of the hardware 
control blocks. In particular, you must understand the immediate device control 
block (IDCB) and the optional device control block (DCB). These control blocks 
contain the I/O operation code and other information the attachment needs to iss 
I/O to the device. 

The hardware description manual for the device or attachment you support normally 
contains information on these control blocks and how you use them. 

What Types of Device Interrupts Should You Plan For? 

If the device produces interrupts, your device support must supply all required 
information needed to service the interrupts. In addition, your device support must 
prepare the device for interrupts as well as disable interrupts when the task ends. 

You would typically have separate tasks in your program to handle device interrupts 
and post events. 

Normally, you obtain information on device interrupts from the hardware device 
description manual. 

Does the Device Have Any Special Timing Considerations? 

You must determine if your device has any unique timing requirements. For 

example, the amount of time in which an interrupt must be serviced or a data 

transfer completed. If timing is critical for the device, you may have to establish 

task priorities. You may also have to consider performance differences using EXIO /<"~\ 

versus Series/ 1 assembler code. \^ ) 

Do You Have to Detect and Handle Errors? 

The attachment reports status at the start of and after the completion of an I/O 
operation. This information is returned as status words and condition codes. You 
must design your device support to detect and handle any errors it encounters. 

All possible error conditions should be described in the hardware device description 
manual. 

The device description manual describes the possible errors you could encounter and 
how they are reported. 

How Many Devices Will You Support? 

The number of devices you support may determine how you design the support. 
Normally, if you only support one device from one program, the EXIO code and 
much of the data and device control information can reside in that program. 

When you support multiple devices, you must provide a copy of the data and device 
control information for each device. 



^"■Utaiw*^ 
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How Many Applications Will Use the Device? 

If multiple applications will request the use of the support at the same time, you 
must serialize the support ' s use. You provide serial use through the ENQ/DEQ 
instructions. Further, if these applications reside in different partitions, you must 
use the system's cross-partition services to move data and device control information 
across the partitions. 

Do You Have to Initialize the Device? 

Some attachments and/or devices require special initiahzation or a random access 
memory load prior to their use. EDX does not initiahze devices you define as an 
EXIO device. Device initiahzation is your responsibility. 

You must also know the engineering change (EC) level of your device. Different 
device EC levels may require that you select from various random access memory 
load modules at initialization. The EC level and initiahzation code must match for 
the device. 



Defining the Device at System Generation 

You use the EXIODEV statement to define your device at system generation. The 
device you define must not be defined in the system by any other configuration 
statement. 

If your device support performs cycle steal operations or requires chained DCBs to 
complete an operation, you must specify the MAXDCB = operand. In addition, 
cycle steal operations return residual status information. You must specify the 
RSB = operand to indicate the number of residual status bytes returned from the 
operation. 

The supervisor must also contain EXIO support modules. You must specify 
INCLUDE statements for the modules lOSEXIO and EXIOINIT in your hnk 
control data set. 

The EXIODEV statement is discussed in the Installation and System Generation 
Guide. 
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Writing the EXIO Code 



This section explains a sample program that uses EXIO to control a device. The 
3101 Model 1 terminal (character mode) is the device used and is connected to the 
2095/2096 Feature Programmable multiline attachment. The program provides 
support for expanded mode (with continuous receive) and one stop bit during data 
transmission. 

Controlhng a device with continuous receive enables a receive channel for the device 
to be open at all times. You would use this feature under EXIO when a device 
requires input at a speed at which EDL terminal I/O instructions cannot provide. 

The sample program, when loaded, prompts for input, loops to receive ten lines of 
input, and prints the input on the printer. 

The instructions and statements the program uses to perform I/O operations to the 
device are: EXIO, EXOPEN, IDCB, and DCB. Refer to the Language Reference 
for the coding syntax and description of these instructions and statements. 

The EXIODEV statement for this device follows: 



o 



EXIODEV ADDRESS=60,MAXDCB=1,RSB=6,END=YES 



As with any support you provide using EXIO, you must understand the \^_^ 

characteristics of the device or attachment. The IBM Series/ 1 Communications 
Features Description, GA34-0028 can assist you in understanding the I/O operations 
to the attachment used in the sample program. 

Preparing the Device for Interrupts 

Before the program issues any I/O operations to the device, it must initiate all 
interrupt handling tasks, open the device, and prepare the device for interrupts. 

The interrupt handling tasks are separate tasks which the (main) program attaches. 
Each task waits for the hardware to post an ECB indicating an interrupt has 
occurred. When the hardware posts the ECB, the task does some processing and 
posts an ECB in the main program to indicate the interrupt has been serviced. After 
the task posts the main program, the interrupt handhng task waits again for the next 
interrupt. 
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The tasks in this program service the following types of interrupts: 

• Device end interrupts 

• Controller end interrupts 

• Exception interrupts. 

The descriptions and code for the interrupt handling tasks are explained in the 
sections below. 

Device End Interrupt Task 

This program uses the task DEVINT to wait on and service device end interrupts. A 
device end interrupt indicates that the device was able to successfully complete the 
program ' s I/O request. 

This task waits for the hardware to post the event control block DEVEND. The 
main program waits for this task to post DONEECB. 

The code that handles device end interrupts follows: 



DEVINT TASK 


DEVSTART 




DEVSTART WAIT 


DEVEND 


WAIT FOR DEVICE END INTERRUPT 


RESET 


DEVEND 




POST 


DONEECB,-! 




GOTO 


DEVSTART 




ENDTASK 







Controller End Interrupt Task 

This program uses the task ENDINT to wait on and service controller end 
interrupts. A controller end interrupt indicates that the attachment can now accept 
an I/O request (no longer busy). 

This task waits for the hardware to post the event control block CENDECB. The 
main program waits for this task to post CTLREND. 

The code that handles controller end interrupts follows: 



^H||iij||iiF 



ENDINT TASK 


CTLSTART 




CTLSTART WAIT 


CENDECB 


WAIT FOR CONTROLLER END INTERRUPT 


RESET 


CENDECB 




POST 


CTLREND,-! 




RESET 


CTLREND 




GOTO 


CTLSTART 




ENDTASK 
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Exception Interrupt Task 

This program uses the task EXCINT to wait on and service exception interrupts. 
An exception interrupt indicates that the device was unable to perform the I/O 
request successfully. 






When an exception occurs, this task examines the hardware status information and 
prints the information on the printer. 

This task also examines word 1, bit 15 of the cycle steal status. When bit 15 is on, a 
buffer overrun condition exists. This task signals a buffer overrun condition by 
posting DONEECB with a value of 2. The main program must then issue a "read 
adapter buffer" operation. 

The code that handles exception interrupts follows: 



WAIT FOR EXCEPTION INTERRUPT 



EXCSTART 

EXCEPT 

EXCEPT 

(INTWORD,EQ,X'AO', BYTE), THEN SHORT RECORD 
DONEECB,-! POST GOOD RETURN 



EXCINT TASK 
EXCSTART WAIT 
RESET 
IF 

POST 
ELSE 

IF (INTW0RD,EQ,X'20', BYTE), THEN LONG RECORD 

PRINTEXT '@LONG RECORDI?' 
ELSE 

IF (INTW0RD,EQ,X'80', BYTE), AND, ((SCSSDATA+2),EQ, 
X' 40', BYTE), THEN TIME-OUT 

PRINTEXT '@TIME-OUT@' 
ELSE 

PRINTEXT '0OTHER EXCEPTION INTERRUPT, ' 
ENDIF 
ENDIF 
ENQT $SYSPRTR 
PRINTEXT 'CSS = ' 
PRINTNUM SCSSDATA,3,M0DE=HEX 
PRINTEXT '@INTWORD,LSR,ECB ADDR 
PRINTNUM INTW0RD,3,M0DE=HEX 
PRINTEXT SKIP=1 
DEQT 

MOVE WDl,SCSSDATA+2 
SHIFTL WD1,15 
IF (WD1,EQ,X'8O0O') 
POST DONEECB, 2 
GOTO EXCSTART 
ENDIF 

POST DONEECB, 1 
ENDIF 

GOTO EXCSTART 
ENDTASK 



CYCLE STEAL STATUS 



ISOLATE BIT 15 
BIT 15 = 1 ? 
INDICATE READ ADAPTER BUFFER 



POST ERROR RETURN 



^<.y 



o 
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After the program attaches the interrupt handUng tasks, the program opens and 
prepares the device. The code that performs these functions follows: 



EXIOREC PROGRAM EXSTART 
EXSTART EQU * 

ATTACH 

ATTACH 

ATTACH 

EXOPEN 

EXIO 



DEVINT DEVICE END INTERRUPT HANDLING TASK 
EXCINT EXCEPTION INTERRUPT HANDLING TASK 
ENDINT CONTROLLER END INTERRUPT HANDLING TASK 
60,INTW0RK,ERR0R=0PENERR OPEN BASE LINE 
PREIDCB,ERROR=PREPERR ENABLE INTERRUPT 



PRINTEXT '^DEVICE OPEN AND PREPAREDia' 



CALL 



SETMODE 



Next the program must establish the mode of transmission. The next section 
explains how this is done. 



Establishing the Transmission Mode 

The program calls a subroutine (SETMODE) to establish the transmission mode. 
SETMODE estabhshes the transmission mode as being expanded mode (with 
continuous receive) using one stop bit. 

The code for the SETMODE subroutine follows: 



SUBROUT SETMODE 

EXIO RESET DEVICE RESET 

******************************************************************** 

* ISSUE SET MODE DCB TO CHANGE * 

* NUMBER OF STOP BITS TO ONE * 

******************************************************************** 

RESET DONEECB 

EXIO SETIDCB,ERROR=SETERR 

WAIT DONEECB 

******************************************************************** 

* ISSUE SET EXPANDED MODE DCB * 

* TO SET CONTINUOUS RECEIVE * 

RESET DONEECB 

EXIO EXPIDCB,ERROR=EXPERR 

WAIT DONEECB 

RETURN 
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SETIDCB is the label of an IDCB statement and points to the label of the DCB 
statement, SETDCB. These two statements define one stop bit: 



SETIDCB IDCB CQMMAND=START,ADDRESS=60,DCB=SETDCB 

****************************************************************** 

* DEVMOD SETUP FOR SET MODE 1 STOP BIT * 

* 9600BPS=O7 CR=OD LF=OA * 
******************************************************************** 



SETDCB DCB 



DEVM0D=B4 , DVPARM1=070D , DVPARM2=0AOO 



On the DCB statement, the value for the DEVMOD = operand is B4. This value 
sets word (bits 8-15) of the device control block to the binary value 10110100. 
These bit settings indicate the following: 

• Set mode 

• Asynchronous operation 

• Eight bits per character 

• One stop bit 

• Odd parity 

• Parity disabled. 

EXPIDCB is also the label of an IDCB statement and points to the label of the 
DCB statement, EXPDCB. These two statements define expanded mode with 
continuous receive: 



EXPIDCB IDCB 



COMMAND=START , ADDRESS=60 , DCB=EXPDCB , M0D4=C 



******************************************************************** 

* SET CONTINUOUS RECV MODE * 15 BYTE BUFFER * 

* * IN DEVICE ADAPTER * 

******************************************************************** 



EXPDCB DCB 



DEVMOD=01,DVPARM3=0O01 



V^ 



Note that the operand MOD4 = C is coded on the IDCB statement. This operand 
alters the IDCB and requests a "start control" operation. 

The DVPARM3==0001 operand on the DCB statement sets word 3 (bit 15) of the 
device control block to indicate continuous receive. 

After the program establishes the mode of transmission, the program writes a 
prompt message to the terminal. This sequence is described next. 
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Writing Data to the Terminal 

The program requests input by writing the message "ENTER DATA:" to the 
terminal. After writing the message, the program checks for a — 1 return code and 
also a controller (attachment) busy condition. 

Note; For this program, only one port on the attachment is active, however, if 
multiple ports were active, a controller busy condition could occur. This program 
detects and handles controller busy conditions. 

If the controller is busy when the program issues an I/O request to the device, the 
EXIO operation fails. When the EXIO operation fails, you must reset the 
attachment. However, the reset also resets the continuous receive. The program 
calls the SETMODE subroutine to reenable continuous receive. 

The code for the program at this point looks like the following: 






EXIOREC PROGRAM EXSTART 

EXSTART EQU * 

ATTACH DEVINT DEVICE END INTERRUPT HANDLING TASK 

ATTACH EXCINT EXCEPTION INTERRUPT HANDLING TASK 

ATTACH ENDINT CONTROLLER END INTERRUPT HANDLING TASK 

EXOPEN 60,INTWORK,ERROR=OPENERR OPEN BASE LINE 

EXIO PREIDCB,ERROR=PREPERR ENABLE INTERRUPT 

PRINTEXT '©DEVICE OPEN AND PREPARED©' 

CALL SETMODE 

LOOPl EQU * 

********************************************************************* 

* ISSUE TRANSMIT END DCB * 

* TO WRITE MESSAGE TO TERMINAL * 

********************************************************************* 



WRITE 



RESET 


DONEECB 






EXIO 


WRIIDCB 




TRANSMIT END 


MOVE 


RC, EXIOREC 






IF 


(RC,EQ,7) 




TEST FOR CONTROLLER BUSY 


WAIT 


CTLREND 






CALL 


SETMODE 






GOTO 


WRITE 






ENDIF 








IF 


(RC,NE,-1), 


GOTO 


WRERR 


WAIT 


DONEECB 




WAIT FOR COMPLETION OF W 



IF 



(DONEECB, NE,-1), THEN 



CHECK FOR GOOD WRITE 



********************************************************************* 

* INSERT USER ERROR ROUTINE * 

********************************************************************* 

ENDIF 
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The IDCB statement for WRIIDCB points to the DCB labeled WRIDCB. This 
DCB contains the address of the message data (WRDATA). The message data is 
ASCII code and is 16 bytes in length. 

The IDCB and DCB statements for the write operation follow: 



WRIIDCB IDCB COMMAND=START,ADDRESS=60,DCB=WR1DCB 

WRIDCB DCB DEVMOD=O1,DVPARM2=O003,COUNT=16,DATADDR=WRDATA 

* TIMER1=10MS 



The following code defines the message data area: 



* 








WRDATA 


DATA 


X'0D0A' 


CR/LF 




DATA 


X'454E' 


EN 




DATA 


X'5445' 


TE 




DATA 


X'5220' 


R 




DATA 


X'4441' 


DA 




DATA 


X'5441' 


TA 




DATA 


X'203A' 


: 




DATA 


X'2O20' 





The next section describes how the program reads input data from the terminal. 

Reading Data from the Terminal 

The program sets up to do a read operation (with time-out) by issuing an EXIO 
instruction to the IDCB labeled RDIIDCB. The DCB associated with this read 
operation indicates 12 bytes of data will be stored beginning at address RED ATA. 

The IDCB and DCB statements for the read operation follow: 



RDIIDCB IDCB C0MMAND=START,ADDRESS=60,DCB=RD1DCB 

RDIDCB DCB I0TYPE=INPUT,DEVMOD=05,DVPARM2=1O00,COUNT=12, 

DATADDR=REDATA 
* TIMER1=13.6SEC 



V,^ 



The program enters a DO loop that reads a line of input and writes the input 
(RED AT A) to the printer. The program loops 10 times and then prompts for input 
again. If during the loop you enter "END," the program ends. 

Also within the loop, the program checks for a "buffer overrun" condition. The 
program indicates a buffer overrun condition when DONEECB equals 2. The 
program calls the RDBUFF subroutine to handle buffer overrun conditions. 






6-10 SC34-0942 



Adding Your Own Device Support 



The code to perform the read operation within the DO loop follows: 






DO 



10, TIMES 



MOVE REDATA.C ',(40, BYTES) 

* ISSUE RECEIVE WITH TIME-OUT DCB * 

* TO READ DATA FROM TERMINAL * 
************************************************************************ 



READ 



RESET 


DONEECB 


EXIO 


RDIIDCB 


MOVE 


RCEXIOREC 


IF 


(RC,EQ,7) 


WAIT 


CTLREND 


CALL 


SETMODE 


GOTO 


READ 


ENDIF 




IF 


(RC,NE,-1),G0T0,RDERR 


WAIT 


DONEECB 


IF 


(DONEECB, EQ, 2) 


CALL 


RDBUFF 


GOTO 


RDEND 


ENDIF 





RECEIVE WITH TIME-OUT 
TEST FOR CONTROLLER BUSY 



WAIT FOR COMPLETION OF READ 



IF 



(DONEECB, NE,-1), THEN 



CHECK FOR GOOD READ 



************************************************************************ 



INSERT USER ERROR ROUTINE 



************************************************************************ 



RDEND 



END 



ENDIF 

ENQT 

PRINTEXT 

PRINTNUM 

PRINTEXT 

DEQT 

EQU 

IF 

ENDDO 

GOTO 

PROGSTOP 



$SYSPRTR 

'@INPUT DATA FROM TERMINAL: 

REDATA,10,M0DE=HEX 

SKIP=1 



(REDATA,EQ,ENDDATA,3),G0T0,END TEST FOR "END" 



LOO PI 
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Resetting Buffer Overrun Conditions 

The RDBUFF subroutine performs a "read adapter buffer" operation followed by a 
"start cycle steal status" operation. Both operations must be done to reset a buffer 
overrun condition. 



The RDBUFF subroutine follows: 



SUBROUT 


RDBUFF SUBROUTINE FOR BUFFER OVERRUN 


RESET 


DONEECB 


EXIO 


RDAIDCB,ERROR=RABERR 


WAIT 


DONEECB WAIT FOR COMPLETION OF WRITE 


PRINTEXT 


'CC = ' PRINT COMPLETION CODE 


PRINTNUM 


DONEECB 


PRINTEXT 


SKIP=1 


ENQT 


$SYSPRTR 


PRINTEXT 


'@READ ADAPTER BUFFER: ' 


PRINTNUM 


REDATA,10,M0DE=HEX 


PRINTEXT 


SKIP=1 


DEQT 




RESET 


DONEECB 


EXIO 


CSSIDCB,ERROR=CSSERR 


PRINTEXT 


'laREAD CYCLE STEAL STATUS DCB ISSUED, ' 


WAIT 


DONEECB 


PRINTEXT 


'CC = ' PRINT COMPLETION CODE 


PRINTNUM 


DONEECB 


PRINTEXT 


SKIP=1 


RETURN 





w_ 



J 



o 
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Reporting Error Return Codes 

All EXIO programs should do extensive error checking and reporting. Use the 
ERROR = operand on the EXIO instruction to set up an error exit. The system 
passes control to the label you specify on this operand. The error exits in the sample 
program follow: 






******************************************************************** 


* 


ERROR EXIT SECTION * 


******************************************************************** 


OPENERR 


EQU 


* 




MOVE 


RC,EXIOREC 




PRINTEXT 


■eOPEN FAILED, ' 




GOTO 


ERREND 


PREPERR 


EQU 


* 




MOVE 


RC.EXIOREC 




PRINTEXT 


'©PREPARE FAILED, ' 




GOTO 


ERREND 


SETERR 


EQU 


* 




MOVE 


RC,EXIOREC 




PRINTEXT 


'@SET MODE FAILED, ' 




GOTO 


ERREND 


EXPERR 


EQU 


* 




MOVE 


RC,EXIOREC 




PRINTEXT 


'@SET EXPANDED MODE FAILED, ' 




GOTO 


ERREND 


RABERR 


EQU 


* 




MOVE 


RCEXIOREC 




PRINTEXT 


'©READ ADAPTER BUFFER FAILED, ' 




GOTO 


ERREND 


CSSERR 


EQU 


* 




MOVE 


RCEXIOREC 




PRINTEXT 


'©READ CYCLE STEAL STATUS FAILED, ' 




GOTO 


ERREND 


WRERR 


EQU 


* 




PRINTEXT 


'©WRITE ERROR, ' 




GOTO 


ERREND 


RDERR 


EQU 


* 




PRINTEXT 


'©READ ERROR, ' 


ERREND 


EQU 


* 




PRINTEXT 


'RETURN CODE = ' 




PRINTNUM 


RC 




PRINTEXT 


SKIP=1 




GOTO 


END 



o 
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Sample EXIO Program 



The coding segments throughout this chapter showed you can create your own 
device support. The following is the sample program in its entirety: 



EXIOREC 
EXSTART 



PROGRAM EXSTART 

EQU * 

ATTACH DEVINT DEVICE END INTERRUPT HANDLING TASK 

ATTACH EXCINT EXCEPTION INTERRUPT HANDLING TASK 

ATTACH ENDINT CONTROLLER END INTERRUPT HANDLING TASK 

EXOPEN 60,INTWORK,ERROR=OPENERR OPEN BASE LINE 

EXIO PREIDCB,ERROR=PREPERR ENABLE INTERRUPT 

PRINTEXT '©DEVICE OPEN AND PREPARED?' 

CALL SETMODE 

LOOPl EQU * 
********************************************************************* 

* ISSUE TRANSMIT END DCB * 

* TO WRITE MESSAGE TO TERMINAL * 

********************************************************************* 



TRANSMIT END 

TEST FOR CONTROLLER BUSY 



RESET DONEECB 

WRITE EXIO WRIIDCB 

MOVE RC, EXIOREC 

IF (RC,EQ,7) 

WAIT CTLREND 

CALL SETMODE 

GOTO WRITE 

ENDIF 

IF (RC,NE,-1),G0T0,WRERR 

WAIT DONEECB WAIT FOR COMPLETION OF WRITE 

IF (DONEECB, NE,-1), THEN CHECK FOR GOOD WRITE 
********************************************************************* 

* INSERT USER ERROR ROUTINE * 

********************************************************************* 



ENDIF 

DO 

MOVE 



10, TIMES 
REDATA,C' 



(40, BYTES) 



********************************************************************* 

* ISSUE RECEIVE WITH TIME-OUT DCB * 

* TO READ DATA FROM TERMINAL * 
********************************************************************* 



READ 



RESET 


DONEECB 


EXIO 


RDIIDCB REC 


MOVE 


RC, EXIOREC 


IF 


(RC,EQ,7) TES- 


WAIT 


CTLREND 


CALL 


SETMODE 


GOTO 


READ 


ENDIF 




IF 


(RC,NE,-1),G0T0,RDERR 


WAIT 


DONEECB WAI 


IF 


(DONEECB, EQ, 2) 


CALL 


RDBUFF 


GOTO 


RDEND 


ENDIF 





RECEIVE WITH TIME-OUT 



TEST FOR CONTROLLER BUSY 



WAIT FOR COMPLETION OF READ 






c 



Figure 6-1 (Part 1 of 6). Sample EXIO Program 
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IF (DONEECB, NE,-1), THEN CHECK FOR GOOD READ 

********************************************************************* 

* INSERT USER ERROR ROUTINE * 
********************************************************************* 

ENDIF 

ENQT SSYSPRTR 

PRINTEXT '@INPUT DATA FROM TERMINAL: ' 

PRINTNUM REDATA,10,M0DE=HEX 

PRINTEXT SKIP=1 

DEQT 

RDEND EQU * 

IF (REDATA,EQ,ENDDATA,3),G0T0,END TEST FOR "END" 

ENDDO 

GOTO LOOPl 

END PROGSTOP 

********************************************************************* 

* INTERRUPT TASKS * 
********************************************************************* 

DEVI NT TASK DEVSTART 



DEVSTART 


WAIT 

RESET 

POST 

GOTO 

ENDTASK 


DEVEND 
DEVEND 
DONEECB,-! 
DEVSTART 




WAIT FOR DEVICE END INTERRUPT 


ENDINT 


TASK 


CTLSTART 






CTLSTART 


WAIT 

RESET 

POST 

RESET 

GOTO 

ENDTASK 


CENDECB 

CENDECB 

CTLREND,-! 

CTLREND 

CTLSTART 




WAIT FOR CONTROLLER END INTERRUP 


EXCINT 


TASK 


EXCSTART 






EXCSTART 


WAIT 
RESET 


EXCEPT 
EXCEPT 




WAIT FOR EXCEPTION INTERRUPT 




IF 


(INTWORD,EQ,X'A0' 


, BYTE), THEN SHORT RECORD 




POST 


DONEECB,-! 




POST GOOD RETURN 




ELSE 










IF 


(INTWORD,EQ 


,X'20' 


, BYTE), THEN LONG RECORD 



PRINTEXT '@LONG RECORD?' 
ELSE 

IF (INTWORD,EQ,X'80', BYTE), AND, ((SCSSDATA+2),EQ, 

X'40', BYTE), THEN TIME-OUT 

PRINTEXT '@TIME-OUT@' 
ELSE 

PRINTEXT 'POTHER EXCEPTION INTERRUPT, ' 
ENDIF 
ENDIF 



Figure 6-1 (Part 2 of 6). Sample EXIO Program 
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ENQT 


$SYSPRTR 




PRINTEXT 'CSS = ' 




PRINTNUM SCSSDATA,3,M0DE=HEX CYCLE STEAL STATUS 




PRINTEXT '@INTWORD,LSR,ECB ADDR : ' 




PRINTNUM INTW0RD,3,M0DE=HEX 




PRINTEXT SKIP=1 




DEQT 






MOVE 


WDl,SCSSDATA+2 




SHIFTL 


WD1,15 ISOLATE BIT 15 




IF 


(WD1,EQ,X'80O0') BIT 15 = 1 ? 




POST D0NEECB,2 INDICATE READ ADAPTER BUFFER 




GOTO EXCSTART 




ENDIF 






POST 


DONEECB.l POST ERROR RETURN 




ENDIF 






GOTO 


EXCSTART 




ENDTASK 




********************************************************************* 1 


* ERROR 


EXIT SECTION * 


********************************************************************* 1 


OPENERR 


EQU 


* 




MOVE 


RC,EXIOREC 




PRINTEXT 


'@OPEN FAILED, ' 




GOTO 


ERREND 


PREPERR 


EQU 


* 




MOVE 


RC,EXIOREC 




PRINTEXT 


■ePREPARE FAILED, ' 




GOTO 


ERREND 


SETERR 


EQU 


* 




MOVE 


RC,EXIOREC 




PRINTEXT 


'@SET MODE FAILED, ' 




GOTO 


ERREND 


EXPERR 


EQU 


* 




MOVE 


RC,EXIOREC 




PRINTEXT 


■@SET EXPANDED MODE FAILED, ' 




GOTO 


ERREND 


RABERR 


EQU 


* 




MOVE 


RCEXIOREC 




PRINTEXT 


'@READ ADAPTER BUFFER FAILED, '' 




GOTO 


ERREND 


CSSERR 


EQU 


* 




MOVE 


RCEXIOREC 




PRINTEXT 


'@READ CYCLE STEAL STATUS FAILED, ' 




GOTO 


ERREND 


WRERR 


EQU 


* 




PRINTEXT 


■@WRITE ERROR, ' 




GOTO 


ERREND 


RDERR 


EQU 


* 




PRINTEXT 


'(aREAD ERROR, ' 


ERREND 


EQU 


* 




PRINTEXT 


'RETURN CODE = ' 




PRINTNUM 


RC 




PRINTEXT 


SKIP=1 




GOTO 


END 



Figure 6-1 (Part 3 of 6). Sample EXIO Program 
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********************************************************************* 

* SUBROUTINES * 

********************************************************************* 



SUBROUT SETMODE 



EXIO 



RESET 



DEVICE RESET 



********************************************************************* 

* ISSUE SET MODE DCB TO CHANGE * 

* NUMBER OF STOP BITS TO ONE * 
********************************************************************* 

RESET DONEECB 

' EXIO SETIDCB,ERROR=SETERR 

WAIT DONEECB 
********************************************************************* 

* ISSUE SET EXPANDED MODE DCB * 

* TO SET CONTINUOUS RECEIVE * 
********************************************************************* 



RESET 


DONEECB 


EXIO 


EXPIDCB,ERROR=EXPERR 


WAIT 


DONEECB 


RETURN 




SUBROUT 


RDBUFF 


RESET 


DONEECB 


EXIO 


RDAIDCB,ERROR=RABERR 


WAIT 


DONEECB 


PRINTEXT 


■CC = ' 


PRINTNUM 


DONEECB 


PRINTEXT 


SKIP=1 


ENQT 


SSYSPRTR 


PRINTEXT 


■@READ ADAPTER BUFFER 


PRINTNUM 


REDATA,10,MODE=HEX 


PRINTEXT 


SKIP=1 


DEQT 




RESET 


DONEECB 


EXIO 


CSSIDCB,ERROR=CSSERR 


PRINTEXT 


'@READ CYCLE STEAL SJi 


WAIT 


DONEECB 


PRINTEXT 


'CC = ' 


PRINTNUM 


DONEECB 


PRINTEXT 


SKIP=1 



SUBROUTINE FOR BUFFER OVERRUN 



WAIT FOR COMPLETION OF WRITE 
PRINT COMPLETION CODE 



PRINT COMPLETION CODE 



RETURN 
********************************************************************* 

* DATA BUFFERS * 

********************************************************************* 



WRDATA 



DATA 


X'ODOA' 


CR/LF 


DATA 


X'454E' 


EN 


DATA 


X'5445' 


TE 


DATA 


X'5220' 


R 


DATA 


X"4441' 


DA 


DATA 


X'5441' 


TA 


DATA 


X'203A' 


: 


DATA 


X'2020' 





Figure 6-1 (Part 4 of 6). Sample EXIO Program 
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REDATA DATA 
ENDDATA DATA 
SCSSDATA DATA 
RC DATA 
WDl DATA 



20F'0' 

X'454E4400' 

3F'0' 

F'0' 

F'0' 



ASCII END 
6 BYTE OF CYCLE STEAL STATUS 



********************************************************************* 

* INTERRUPT DEFINE INFORMATION * 

********************************************************************* 

INTERRUPT BYTE AND ADDRESS SAVE AREA 

INTERRUPT CONDITION CODE ECB 

START CYCLE STEAL STATUS DCB 

INTERRUPT STATUS / DEVICE ADDRESS 

LSR AT TIME OF INTERRUPT 

ADDRESS OF ECB POSTED 

CC=0 

CC=1 

CC=2 EXCEPTION 

CC=3 DEVICE END 

CC=4 

CC=5 

CC=6 



INTWORK 


DC 


A (INTWORD) 




DC 


A(INTECB) 




DC 


A(SCSSDCB) 


INTWORD 


DATA 


F'0' 




DATA 


F'0' 




DATA 


F'0' 


INTECB 


DATA 


A(CENDECB) 




DATA 


A(NA) 




DATA 


A(EXCEPT) 




DATA 


A(DEVEND) 




DATA 


A(NA) 




DATA 


A(NA) 




DATA 


A(NA) 



DATA 



A(NA) 



CC=7 



********************************************************************* 



RESET 


I DCB 


COMMAND- 


PREIDCB 


IDCB 


COMMAND 


SETIDCB 


IDCB 


COMMAND 


EXPIDCB 


IDCB 


COMMAND 


WRIIDCB 


IDCB 


COMMAND 


RDIIDCB 


IDCB 


COMMAND 


RDAIDCB 


IDCB 


COMMAND 


CSSIDCB 


IDCB 


COMMAND 



* IMMEDIATE DEVICE CONTROL BLOCKS * 
********************************************************************* 

=RESET,ADDRESS=60 

=PREPARE,ADDRESS=60,LEVEL=1,IBIT=ON 

=START , ADDRESS=60 , DCB=SETDCB 

=START,ADDRESS=60,DCB=EXPDCB,MOD4=C 

=START , ADDRESS=60 , DCB=WR1DCB 

=START , ADDRESS=60 , DCB=RD1DCB 

=START , ADDRESS=60 , DCB=RDADCB 

=START , ADDRESS=60 , DCB=SCSSDCB , M0D4=F 
********************************************************************* 

* DEVICE CONTROL BLOCKS * 
********************************************************************* 

SETDCB DCB DEVMOD=B4,DVPARM1=070D,DVPARM2=0A00 

* DEVMOD SETUP FOR SET MODE 1 STOP BIT 

* 96OOBPS=07 CR=0D LF=0A 
EXPDCB DCB DEVMOD=01,DVPARM3=0001 

* SET CONTINUOUS RECEIVE MODE ** 15 BYTE BUFFER ** 

* * IN DEVICE ADAPTER * 
DCB DEVM0D=01 , DVPARM2=OO03 , C0UNT=16 , DATADDR=WRDATA 

TIMER1=10MS 
DCB IOTYPE=INPUT,DEVMOD=05,DVPARM2=1O00,COUNT=12, C 
DATADDR=REDATA 



WRIDCB 
* 

RDIDCB 



* TIMER1=13.6SEC 

********************************************************************* 



* READ ADAPTER BUFFER DCB * 

********************************************************************* 

RDADCB DCB I0TYPE=INPUT,DEVM0D=74,C0UNT=I4,DATADDR=REDATA 

* 

SCSSDCB DCB I0TYPE=INPUT,C0UNT=6,DATADDR=SCSSDATA 



Figure 6-1 (Part 5 of 6). Sample EXIO Program 
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CENDECB 


ECB 





EXCEPT 


ECB 





DEVEND 


ECB 





NA 


ECB 


. 


DONEECB 


ECB 





CTLREND 


ECB 






********************************************************************* 

* EVENT CONTROL BLOCKS * 
********************************************************************* 

INTERRUPT CONDITION CODE 

INTERRUPT CONDITION CODE 2 

INTERRUPT CONDITION CODE 3 

NOT USED, PAPER WORK ONLY 

OPERATION 

CONTROLLER END ECB 
********************************************************************* 

* THIS ECB WILL BE WAITED ON BY ANY LINE ATTACHED * 

* TO THE CONTROLLER AT ADDRESS 60 WHEN THE LINE * 

* GETS A CONTROLLER BUSY CONDITION. THE CONTROLLER * 

* END INTERRUPT WILL COME BACK ON THE BASE ADDRESS 60 * 

* FOR ANY LINE ATTACHED TO THE CONTROLLER. * 
********************************************************************* 

ENDPR06 
END 



Figure 6-1 (Part 6 of 6). Sample EXIO Program 



Chaining DCBs in a Circle 

EXIO allows you to chain DCBs together in a circle. Once you initiate the I/O with 
an EXIO start I/O request, you can "break" these chained DCBs with the 
EXBREAK instruction. For more information on the EXBREAK instruction, refer 
to the Language Reference. 

The following EXBREAK example specifies address 21 and says to break after DCB 
number 4. 



EXBREAK 



21,4 



Sample Program 



The following EXIO program prints data to a 4973/74 printer at hardware address 
X'2r All DCBs used are chained together, with the last DCB chained to the first 
(hence the "circular" chained DCBs). Each DCB points to a unique message that 
the system will print endlessly until the operator enters an ATTENTION BREAK. 
This command breaks the chain at DCB 2, and prints the DCB 2 buffer, as follows: 






THIS IS DCB 1 
THIS IS DCB 2 
THIS IS DCB 3 
THIS IS DCB 1 
THIS IS DCB 2 
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A sample program for circular chained DCBs follows. 



TEST 


PROGRAM 


START 






ATTN LI ST 


(BREAK, BREAKIT) 




BREAKIT 


EQU 


* 






EXBREAK 


21,02 


BREAK CHAIN AT DCB2 




ENDATTN 






START 


EQU 


* 






RESET 


EXCOMM 


RESET ECB 




RESET 


EXDUMMY 


RESET ECB 


RETOPEN 


EXOPEN 


21,EXI0ADDR 


OPEN EXIO 




TCBGET 


TCBRT, $TCBCO 


GET RETURN CODE 




IF (TCBRT 


,NE,+OK) 


OK? 




IF (TCBRT, EQ,+TWO), GOTO, RETOPEN 


RETRY IF BUSY 




PRINTEXT 'EXOPEN COMMAND FAILED^ 


' 




GOTO STOP 






ENDIF 








ENDIF 








EXIO 


PREPARE 


PREPARE DEVICE 
FOR INTERRUPTS 




EXIO 


RESET 


RESET DEVICE 




RESET 


EXCOMM 


RESET ECB 




RESET 


EXDUMMY 


RESET ECB 


RETEXIO 


EXIO 


STARTIO 






TCBGET 


TCBRT, $TCBCO 


GET TCB ADD 




IF (TCBRT 


,NE,+OK) 


OK? 




IF (TCBRT, EQ,+TWO), GOTO, RETEXIO 


RETRY IF BUSY 




PRINTEXT 'EXIO COMMAND FAILED?' 






ENDIF 








ELSE 








WAIT 


EXCOMM 


WAIT FOR END 




AND 


EXCOMM, X'0F0O',RESULT=CCCODE GET RETURN CODE 




SHIFTR 


CCC0DE,8 


RIGHT JUSTIFY 




IF 


(CCCODE,NE,+THREE) 


DEVICE END 




PRINTEXT 'ERROR FROM EXIO STARTIO@' | 




ENDIF 








ENDIF 






STOP 


PROGSTOP 






*****i(**i(*ic*i(****it*ic*ie***ic*iciei(i(****ie**ie*-k******ie******-kit****-k**ieie**** 1 


* IDCBs 






* 


********************************************************************* 1 


PREPARE 


IDCB 


COMMAND=PREPARE,ADDRESS= 


21,LEVEL=1,IBIT=0N 


RESET 


IDCB 


C0MMAND=RESET,ADDRESS=21 




STARTIO 


IDCB 


C0MMAND=START,ADDRESS=21 


,DCB=DCB01 



Figure 6-2 (Part 1 of 2). Sample Program for Circular Chained DCBs 
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************************************************************************* 

* DCBs ARE IN A CIRCULAR CHAIN. THE LAST ONE * 

* ONE (DCB03) POINTS TO THE FIRST ONE (DCBOl) . * 

I0TYPE=0UTPUT,DVPARM1=3000,DVPARM2=0001, 

CHAINAD=DCB02,COUNT=16,DATADDR=TEXT1 

IOTYPE=OUTPUT,DVPARM1=3OOO,DVPARM2=O0O1, 

CHAI NAD=DCB03 , C0UNT=16 , DATADDR=TEXT2 

IOTYPE=OUTPUT,DVPARM1=3OO0,DVPARM2=OOO1, 

CHAINAD=DCB01,C0UNT=16,DATADDR=TEXT3 
********************************************************************* 

* TEST DATA TO BE PRINTED * 
********************************************************************* 



DCBOl 


DCB 


DCB02 


DCB 


DCB03 


DCB 



TEXTl 
TEXT2 
TEXT3 



TEXT 'THIS IS DCB 1 ',LENGTH=16 
TEXT 'THIS IS DCB 2 '5LENGTH=16 
TEXT 'THIS IS DCB 3 ',LENGTH=16 



********************************************************************* 



WORK AREA AND EQUATES 



********************************************************************* 



CCCODE 


DATA 


F'O' 




TCBRT 


DATA 


X'FFFF' 


TCB RETURN CODE 




DATA 


X'FFFF' 


TCB RETURN CODE 


OK 


EQU 


X'FFFF' 


TCB RETURN CODE 


TWO 


EQU 


2 




THREE 


EQU 


3 





DEV DATA F'O' SAVE AREA FOR DEVICE ADDRESS 
********************************************************************* 

* EXOPEN INSTRUCTION PARAMETERS * 

********************************************************************* 



EXIOADDR 


DATA 


A(EXIOl) 


POINTER TO 3-WORD INTERRUP 
BLOCK 




DATA 


A(EXECBS) 


ADDRESS OF ECB'S ADDRESSES 




DATA 


A(EXSCSDCB) 


ADDRESS OF SCSS DCB 


EXIOl 


DATA 


F'O' 


INTERRUPT ID WORD 




DATA 


F'O' 


LSR AT INTERRUPT 



DATA F'O' ADDRESS OF ECB POSTED 

********************************************************************* 

* INTERRUPT CONDITION CODES * 

********************************************************************* 

CC=0 N,R 
CC=1 N,R 
CC=2 EXCEPTION 
CC=3 DEVICE END 
CC=4 N-,R 
CC=5 N,R 
CC=6 N,R 
CC=7 N,R 
:0UNT=16,DATADDR=SSTDA 
CYCLE-STEAL STATUS 

COMMON ECB 

DUMMY ECB (IGNORE THESE POSTS) 



EXECBS 


DATA 


A (EXDUMMY) 




DATA 


A(EXDUMMY) 




DATA 


A (EXCOMM) 




DATA 


A (EXCOMM) 




DATA 


A (EXCOMM) 




DATA 


A (EXCOMM) 




DATA 


A (EXCOMM) 




DATA 


A(EXCOMM) 


EXSCSDCB 


DCB 


IOTYPE=INP 


SSTDATA 


DATA 


8F'0' 


EXSCSWDS 


DATA 


3F'0' 


EXCOMM 


ECB 





EXDUMMY 


ECB 

ENDPROG 

END 






SCSS DCB 



Figure 6-2 (Part 2 of 2). Sample Program for Circular Chained DCBs 



Chapter 6. Adding Your Own Device Support 6-21 






o 



6-22 SC34-0942 



Creating Your Own EDL Instruction 



Chapter 7. Creating Your Own EDL Instruction 

If the Event Driven Language (EDL) does not provide an instruction that performs 
a function you need, you can create your own instruction to provide that function. 
This chapter explains how you can build an instruction that you can compile using 
SEDXASM. 

The Internal Design provides a detailed discussion of how SEDXASM processes 
EDL instructions. 

One of the steps to implement a new EDL instruction will require you to write some 
Series/ 1 assembler code. You will need the Series/ 1 Macro Assembler (SSIASM) in 
that step. 



Defining the Instruction Requirements 



O 



The first step in creating a new instruction is defining what function the instruction 
will perform. The function the instruction performs determines the coding syntax as 
regards the use of: 

• positional operands 

• keyword operands 

• indexable operands. 

This chapter explains how to create a sample EDL instruction called NEWCMD. 
NEWCMD has the following characteristics: 

• One positional operand 

• Two optional keyword operands (one of which is PI =) 

• Two indexable operands 

• Adds the value 1 to operand one, or 

• Adds the value of the keyword parameter to operand one 

• Generates a new operation code. 

The system reserves two operation codes for your use: 01 and 02. The NEWCMD 
instruction will use 01 as the new operation code. 

Defining the characteristics hsted above, you could code NEWCMD any of the 
following ways: 



LABELl 


NEWCMD 


X 


ADD 1 TO X 


LABEL2 


NEWCMD 


X,KWD=Y 


ADD VALUE OF Y TO X 


LABELS 


NEWCMD 


X,KWD=Y,P1=Z 


ADD VALUE OF Y TO X 


LABEL4 


NEWCMD 


X,KWD=(4,#1) 


ADD VALUE AT (4,#1) TO X 



After you define the function and syntax of the instruction, you must define a model 
of the instruction in an overlay program. This is discussed next. 
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Creating an Overlay Program to Build the Instruction 

You define a model of the instruction in an overlay program. In addition, the 
overlay program contains statements and subroutines that check syntax and build 
object code for the new instruction. 

Note: The overlay program you supply is unique to SEDXASM. Do not confuse 
the overlay program discussed in this chapter with EDL or SEDXLINK overlays. 

A brief description of the statements you can use follows. These statements are 
described in detail in the section "Overlay Program Statements" on page 7-25. 

$IDEF Defines a model or prototype instruction. 

ASMERROR Generates syntax error messages. 

OTE Defines an object text element. 

SLE Defines a sublist element. 

The subroutines you can use follow. These are described in detail in the section 
"Overlay Program Subroutines" on page 7-30. 

SINDEX Examines operands for index register usage. 

BLDTXT Builds object text from object text elements. 

GETVAL Evaluates character strings from a subhst element. 

LABELS Defines or resolves labels for symbol table entries. 

MOVEBYTE Moves a byte string to a target location. 

OPCHECK Checks instruction syntax and builds object code for each operand. 

SLPARSE Divides (parses) an input string into sublist elements. 

You may use any or all of these statements and subroutines in the overlay program 
you create. The overlay program for the NEWCMD instruction uses $IDEF, 
SINDEX, ASMERROR, and OTE. 

Building the Model Instruction 

You use the $IDEF statement to build a model of the instruction. When you code 
$IDEF, you specify the positional operands and keywords of the instruction. The 
number of positional and keyword operands for an instruction must not exceed 50. 

You can optionally specify error exits on SIDEF for invalid syntax. These error 
exits are used in conjunction with the ASMERROR statement. 

Note: For detailed examples of the operands and keyword parameters, refer to the 
section "Analyzing and Checking Source Statement Syntax" in the Internal Design. 



Vy 
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Coding $IDEF for the NEWCMD Instruction 

In the following example, the instruction NEWCMD is defined with one positional 
(OPl) and two keyword (KWD and PI) operands. The error exits are at labels 
ERROR2 and ERRORS. 



The $IDEF statement coded for NEWCMD in the overlay program looks as 
follows: 



ASMOLAYX PROGRAM 


BEGIN 


BEGIN EQU 


* 


NEWLIST $IDEF 


OPl , ( KWD , PI) , PERR=ERR0R2 , KERR=ERR0R3 


ERR0R2 • 




ERRORS • 





Checking the Source Statement Syntax 

When SEDXASM parses the NEWCMD instruction, it builds tables and pointers 
and stores this data in the compiler common area. SEDXASM passes the address of 
this area as a 1 -word parameter. Your overlay program must refer to this parameter 
as SPARMl and then move it to either software register #1 or #2. Using the 
ASMCOMM equates, you can then access the fields in the common area. You use 
these fields to check syntax and build object text. 



To illustrate how SEDXASM parses an instruction. Figure 7-1 on page 7-4 shows 
an example of the parsed output if you coded the NEWCMD instruction as follows: 



SAMPLE NEWCMD A,KWD=(4,#1) ,P1=X 



An explanation follows the example. 
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12 3 4 

12 3456789012 3456789012345678901234567890 



SAMPLE 



OLE DATA 
OLELENG 
OLESLE 

OLESLE# 
OLEKEYWD 



SLEDATA 
SLELENG 
SLETYPE 
SLECHAIN 



SLEDATA 
SLELENG 
SLETYPE 
SLECHAIN 



NEWCMD 
0LE1 



[ 



0020 




0001 




A(SLE1) 




0001 


0000 








SLE1 


r 




0020 




0001 















(ALABEL,#1) 



A(SLEO) 



SLEO 



0001 



0006 



A,KWD=(4,#1) ,P1=X 
0LE3 



ULCZ 



0026 



0006 



A(SLE2) 



0002 



A(KEY1) 



SLE2 



0027 



0001 



SELFDEF 



A(SLE3) 



0036 



0001 



A(SLE4) 



0001 



A(KEY2) 



SLE4 



0036 



0001 



^ KWD 



SLE3 



PI 



0029 



0002 



Keyword 
table 



(0PC0DE,#1) 



NEWCMD 



Figure 7-1. Source Statement Parsing Example 



'Vy 



Operation name 

A0942001 



In this example, software register #1 points to the compiler common area, 
ASMCOMM. SEDXASM begins the parsing operation with the label SAMPLE 
and stores the results in the location (ALABEL,#1). SEDXASM creates a subhst 
element (SLE) for the label. A subhst element has four fields: SLEDATA, 
SLELENG, SLETYPE, and SLECHAIN. SLEDATA points to the first character 
of a label or operand. SLELENG is the number of characters in the label or 
operand. SLETYPE is the type of subhst element. SLECHAIN is used internally 
for creating chained sublist elements. 
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The SLETYPE field can have the value (undefined), 1 (self-defining term), or 2 
(string). 

Self-defining terms are decimal constants (for example, 5, 1000, and -32000), 
hexadecimal constants (for example, X' 1234", X'FF', and X' AOBO'), EBCDIC 
constants (for example, C A' and C 12'), or symbols preceded by a + or — sign 
(for example, +LABEL1, +$DSCBLEN, and -LABEL2). 

SLETYPE is "string" if the entire operand is enclosed in quotes. In this case, 
SEDXASM scans the entire data string for embedded double quotes which signify an 
apostrophe. If double quotes are found, SEDXASM changes them to single quotes 
and adjusts the SLE length field (SLELENG) accordingly. 

In Figure 7-1 on page 7-4, the SLED ATA pointer for the label is 1, the field length 
is 6, and the type is undefined. If the source statement has no label, the compiler 
sets (ALABEL,#1) to 0. 

SEDXASM enters the operation name (EDL instruction) in the field (OPCODE,#l). 
The compiler also generates a table of operand list elements that describe the coded 
operands. The word (AOPTABLE,#l) is the pointer to this table. 

The table has a 10-byte header. Each operand hst element (OLE) in the table is also 
10-bytes in length. One OLE describes each operand. 

An OLE has five fields: OLEDATA, OLELENG, OLESLE, OLESLE#, and 
OLEKEYWD. OLEDATA points to the first character of the operand. 
OLELENG is the number of characters in the operand. OLESLE points to the first 
sublist element (SLE) of the operand. The compiler generates at least one SLE for 
every operand. OLESLE# is the number of SLEs in the operand. If you coded a 
keyword operand, OLEKEYWD points to the entry in the keyword table that 
contains the 1—7 character name of the keyword operand. 

The sample NEWCMD source statement has three operands. The positional 
operand is A. The operand list element OLEl describes this positional operand. 
The keyword operands are KWD = and PI = . These keyword operands are 
described by OLE2 and OLE3, respectively. 

OLEl indicates a 1 -character operand at relative address 0020, with one SLE 
(SLEl). The operand type is undefined. OLE2 shows a 6-character operand 
beginning at 0026, with two SLEs (SLE2 and SLE3). SLE2 points to the constant 4 
and SLE3 points to #1. OLE3 shows a 1 -character operand at 0036, with one SLE 
(SLE4). SLE4 points to the X, whose type is undefined. SEDXASM stores the 
names of the keywords (KWD and PI ) in the keyword table. 

The following code shows how to receive the address of the compilei; common area 
and check for a vahd instruction name. Control passes to label #NEWCMD upon a 
match; otherwise, control passes to label ERRORl. 
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ASMOLAYX 


PROGRAM 


BEGIN, 300, PARM=1 






COPY 


ASMCOMM COPY CODE FOR EQUATES 




BEGIN 


EQU 


* 






MOVE 


#l,$PARMi GET ADDR OF COMMON AREA 






IF 


((OPCODE, #1) ,EQ, CNEWCMD, 8) , GOTO, #NEWCMD 


CODE OK? 


ERRORl 


• 
• 






CNEWCMD 


• 
DC 


CLS'NEWCMD' 




#NEWCMD 


EQU 


* 





J 



You must now write the code to check syntax and handle syntax errors. You use 
the OPCHECK subroutine to check syntax against the model instruction. You use 
the ASMERROR statement to issue syntax error messages. 

Using the sample overlay program, the code to check syntax and issue syntax error 
messages is shown: 



ASMOLAYX 


PROGRAM 


BEGIN, 300, PARM=1 




COPY 


ASMCOMM COPY CODE FOR EQUATES 


BEGIN 


EQU 


* 




MOVE 


#1,$PARM1 GET ADDR OF COMMON AREA 




IF 


((OPCODE, #1),EQ, CNEWCMD, 8), GOTO, #NEWCMD CODE OK? 


ERRORl 


ASMERROR 1,$EDXLUSR INVALID INSTRUCTION 


ENDTASK 


EQU 
DETACH 


* SET UP EXIT 




GOTO 


BEGIN 


ERR0R2 


ASMERROR 2,$EDXLUSR INVALID POSITIONAL OPERAND 


ERRORS 


ASMERROR 3,$EDXLUSR INVALID KEYWORD 


ERR0R4 


ASMERROR 4,$EDXLUSR OPERAND ONE MISSING 




ASMERROR 


GENERATE 


CNEWCMD 


DC 


CLB'NEWCMD' 


NEWLIST 


$IDEF 

• 


0P1 , (KWD , PI) , PERR=ERR0R2 , KERR=ERR0R3 MODEL 


#NEWCMD 


• 
EQU 


* 




CALL 


OPCHECK, (NEWLIST) CHECK SYNTAX 



-.-J 



In the previous example, if the instruction name is not NEWCMD, you issue error 
message 1 (invahd instruction) and exit the program. To exit the program, you must 
code the label ENDTASK. ASMERROR statements branch to this label. In 
addition, you must end the overlay program with a DETACH followed by a GOTO 
to the first executable instruction in the overlay program. If the instruction name is 
NEWCMD, control passes to the label #NEWCMD. 



At label #NEWCMD, you call the OPCHECK subroutine. The OPCHECK 
subroutine compares the instruction syntax and fills in the tables and pointers of the 
compiler common area. Upon encountering syntax errors, control passes to the 
appropriate label you define on the $IDEF statement. In this example, ERROR2 
and ERROR3 are the error exits. 
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Building Object Text 

After OPCHECK executes, the tables and pointers in the compiler area contain the 
addresses of the operand Hst elements (OLEs) and sublist elements (SLEs). You use 
this data to build object text. The object text you build is called an object text 
element (OTE). You use the OTE statement to do this. $EDXASM uses OTEs to 
build object code for further processing. 

Before you build OTEs, you must understand the format of the expanded object 
code. This is described next. 

Expanded Object Code Format 

The object code $EDXASM generated for NEWCMD will be either 2 or 3 words, 
depending on whether you specified KWD. This is illustrated in the next three 
examples. The label you code on NEWCMD is the label on the first word of the 
object code. 

The first word is the operation code word and contains a flag byte (bits — 7) and an 
operation code byte (bits 8-15). The operation code byte for NEWCMD contains 
a value of 1 . 

Figure 7-2 and Figure 7-3 show the possible flag bit meanings for NEWCMD: 






Bit 


Meaning 





This bit is on if operand 2 (KWD) is a constant 




Keyword operand is specified (KWD) 


2&3 


Not used 



Figure 7-2. Flag Bit Meanings (Bits — 3) 

Bits 4 — 7 indicate software register usage for operands 1 and 2 as follows: 



Bits/operand 


Register 
not used 


#1 used 

as (x,#l) 


#2 used 

as (x,#2) 


#1 or #2 
used as 
operand 


4 & 5 for op2 


00 


01 


10 


11 


6 & 7 for opl 


00 


01 


10 


11 



Figure 7-3. Flag Bit Meanings (Bits 4 — 7) 
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The second and third words are the address of the OPl and KWD operands 
respectively. Both OPl and KWD can be indexed and KWD can also be a 
self-defining term. If you code KWD, the object code is three words in length. 
Also, bit 1 of the operation code word is set to 1 (on). If you specify PI, PI will be 
the label on the second word. 



o 



The next three examples show the expansion depending on how you code 
NEWCMD: 

For example, if you code: 



LABELl 



NEWCMD 



SEDXASM generates the following object code: 



LABELl 


DC 
DC 


X'0001' 
A(X) 


(bi 


ts 


0- 


-7 


= 0000 0000) 



If you code: 



LABEL2 NEWCMD Y,KWD=Z,P1=AY 



»y 



SEDXASM generates the following object code: 



LABEL2 


DC 


X'4001' 


(bi 


ts 


0- 


-7 = 


= 0100 0000) 


AY 


DC 


A(Y) 













If you code: 



LABELS NEWCMD (4,#1) ,KWD=7,P1=0P1ADDR 
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$EDXASM generates the following object code: 



LABEL3 


DC 


X'CIGI' 


(bits 0-7 = 


= HOG 0001) 


OPIADDR 


DC 
DC 


F'4' 
F'7' 







Defining the Object Text Elements 

Upon completion of the OPCHECK subroutine, you must define and build the 
object text elements. The sample overlay program defines three OTEs for 
NEWCMD. The first OTE definition (NEWOTEl) builds an operation code OTE 
with a code of 1. You use the other two OTEs (NEWOTE2 and NEWOTE3) to 
build object text for the OPl and KWD operands. 

The following code defines the OTEs. In addition, the operation code and label 
from NEWCMD are placed in NEWOTEl: 






NEWLIST 


• 
• 
• 
$IDEF 


OPl , (KWD, PI) , PERR=ERR0R2 , KERR=ERR0R3 MODEL 


NEWOTE 


DC 


F'3' 


NUMBER OF OTES 


NEWOTEl 


OTE 


TYPE=0PC0DE,SLEDATA=1 


SET OP CODE TO 1 


NEW0TE2 


OTE 


TYPE=ADDRESS 


OTE FOR "OPl" 


NEW0TE3 


OTE 


TYPE=ADDRESS 


OTE FOR "KWD" 


#NEWCMD 


EQU 


* 






CALL 


OPCHECK, (NEWLIST) 


CHECK SYNTAX 


* INITIALIZE 


"OP CODE" OTE 






MOVE 


NEW0TE1+0TEDATAP,1 


RESET OP CODE TO 1 




MOVE 


NEW0TE1+0TEDATAL,(ALABEL,#1) INSERT LABEL 



If a label does not exist on NEWCMD, (ALABEL,#1) is zero and SEDXASM does 
not generate a label. Note that although the operation code for NEWOTEl is 
defined as 1 (SLED ATA = 1), the operation code is reset to 1 on the MOVE 
instruction. Throughout your overlay program, you must reset any data fields that 
might change. This is because $EDXASM could call up the program again without 
ever reloading it. 



You must now process the operands of NEWCMD and build object text, 
section describes how you process the OPl operand. 



The next 
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Processing the 0P1 Operand 

You process the OPl operand first by storing the subhst element (SLE) for the PI 
operand in the label field of NEWOTE2. This moves the address of the SLE which 
defines the label on Pi = (if specified) into NEWOTE2. Processing the OPl operand 
in this manner causes the label for operand 1 to be created. 



Because NEWOTE2 is defined as an address OTE, you must store the sublist 
element (SLE) address that defines the label to be generated. In this case, OPl +2 
contains the SLE address that defines the label. 

Since OPl is indexable, you must also indicate if an index register is used for OPl. 
The flag bit settings in the operation code word indicate register usage. You use the 
SINDEX subroutine to store this information in the object text element for 
NEWOTEl. 

The following code processes OPl and stores register usage information. If OPl is 
missing, an error message is issued and the program exits: 



• 
• 
• 

NEWOTEl OTE 


TYPE=0PC0DE,SLEDATA=1 


SET OP CODE TO 1 


NEW0TE2 OTE 


TYPE=ADDRESS 


OTE FOR "OPl" 


NEW0TE3 OTE 


TYPE=ADDRESS 


OTE FOR "KWD" 


#NEWCMD EQU 


* 




CALL 


OPCHECK,(NEWLIST) 


CHECK SYNTAX 


* INITIALIZE " 


OP CODE" OTE 




MOVE 


NEWOTEl+OTEDATAP,! 


RESET OP CODE TO 1 


MOVE 


NEW0TE1+0TEDATAL,(ALABEL,#1) INSERT LABEL 


* PROCESS "OPl 


" OPERAND 




IF 


(OP1+2,EQ,0),GOTO,ERROR4 OPl MISSING? 


MOVE 


NEW0TE2+0TEDATAL,Pl+2 


STORE ADDR OF PI SLE 


MOVE 


NEW0TE2+0TEDATAP,0Pl+2 


STORE ADDR OF OPl SLE 


CALL 


$INDEX, OPl, NEWOTEl+OTEDATAP, (NEW0TE2),1 



\___V 



Now you must write the code to process the KWD operand. The next section 
describes how you do this. 
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Processing the KWD Operand 

When you process the KWD operand, you must first determine if it was coded on 
NEWCMD. If KWD is not coded, you must set the type field of NEWOTE3 to 
#NULL. This causes SEDXASM to ignore this OTE. 



If KWD is coded, you must reset the type field of NEWOTE3 to #ADDRESS. 
Next, you must set flag bit 1 to 1 in the operation code word. This indicates that 
KWD is specified. 

Because NEWOTE3 is defined as an address OTE, you must store the subHst 
element (SLE) address that defines the data to be generated. In this case, KWD + 2 
contains the SLE address which defines the data. 

Similar to the OPl operand, KWD is also indexable. Again, you use the $INDEX 
subroutine to store the appropriate bits in NEWOTEl. 

The code you use to process the KWD operand follows: 



* PROCESS "KWD" 


OPERAND 


IF 


(KWD+2,EQ,0) KWD SPECIFIED? 


MOVE 


NEW0TE3+0TETYPE,+#NULL SET OTE TYPE TO NULL 


ELSE 




MOVE 


NEW0TE3+0TETYPE,+#ADDRESS RESET TYPE TO ADDRESS 


lOR 


NEW0TE1+0TEDATAP,X'4000' SET FLAG BIT 1 ON 


MOVE 


NEW0TE3+0TEDATAP,KWD+2 STORE ADDR OF KWD 


CALL 


$INDEX,KWD,NEW0TE1+0TEDATAP, (NEW0TE3) ,2 


ENDIF 





You must now write the code to exit the overlay program and return control back to 
SEDXASM. This is described next. 

Ending the Overlay Program 

After you process all the operands, you must store the number of OTEs built in the 
overlay program. You do this by passing the address of the OTE count word, in 
this case NEWOTE. You must then issue a GOTO to the label ENDTASK. 
SEDXASM generates the object code for NEWCMD when the ENDTASK exit is 
taken. 

The code you use to exit the overlay program follows: 



* SET UP EXIT 




MOVEA 


(AMACDATA,#1), NEWOTE STORE OTE COUNT 


GOTO 


ENDTASK 


COPY 


COPCHECK COPY CODE FOR OPCHECK SUBRTN 


COPY 


C$INDEX COPY CODE FOR $INDEX SUBRTN 


ENDPROG 




END 
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Sample Overlay Program for NEWCMD 



The coding segments throughout this section showed you how to create an overlay 
program. The following is the overlay program in its entirety: 



ASMOLAYX 


PROGRAM 


BEGIN,3O0,PARM=1 




COPY 


ASMCOMM COPY CODE FOR EQUATES 


BEGIN 


EQU 


* 




MOVE 


#1,$PARM1 GET ADDR OF COMMON AREA 




IF 


( (OPCODE, #1),EQ, CNEWCMD, 8), GOTO, #NEWCMD CODE OK? 


ERRORl 


ASMERROR 1,$EDXLUSR INVALID INSTRUCTION 


ENDTASK 


EQU 
DETACH 


* SET UP EXIT 




GOTO 


BEGIN 


ERR0R2 


ASMERROR 2,$EDXLUSR INVALID POSITIONAL OPERAND 


ERRORS 


ASMERROR 3,$EDXLUSR INVALID KEYWORD 


ERR0R4 


ASMERROR 4,$EDXLUSR OPERAND ONE MISSING 




ASMERROR 


GENERATE 


CNEWCMD 


DC 


CL8' NEWCMD' 


NEWLIST 


$IDEF 


0P1,(KWD,P1),PERR=ERR0R2,KERR=ERR0R3 MODEL 


NEWOTE 


DC 


F'3' NUMBER OF OTES 


NEWOTEl 


OTE 


TYPE=0PC0DE,SLEDATA=1 SET OP CODE TO 1 


NEW0TE2 


OTE 


TYPE=ADDRESS OTE FOR "OPl" 


NEW0TE3 


OTE 


TYPE=ADDRESS OTE FOR "KWD" 


#NEWCMD 


EQU 


* 




CALL 


OPCHECK, (NEWLIST) CHECK SYNTAX 


* INITIALIZE "OP CODE" OTE | 




MOVE 


NEW0TE1+0TEDATAP,1 RESET OP CODE TO 1 




MOVE 


NEW0TE1+0TEDATAL,(ALABEL,#1) INSERT LABEL 


* PROCESS "OPl" 


OPERAND 




IF 


(OP1+2,EQ,0),GOTO,ERROR4 OPl MISSING? 




MOVE 


NEW0TE2+0TEDATAL,Pl+2 STORE ADDR OF PI SLE 




MOVE 


NEW0TE2+0TEDATAP,0Pl+2 STORE ADDR OF OPl SLE 




CALL 


$INDEX,0P1,NEW0TE1+0TEDATAP,(NEW0TE2),1 


* PROCESS "KWD" 


OPERAND 




IF 


(KWD,EQ,0) KWD SPECIFIED? 




MOVE 


NEW0TE3+0TETYPE,+#NULL SET OTE TYPE TO NULL 




ELSE 






MOVE 


NEW0TE3+0TETYPE,+#ADDRESS RESET TYPE TO ADDRESS 




lOR 


NEW0TE1+0TEDATAP,X'4000' SET FLAG BIT 1 ON 




MOVE 


NEW0TE3+0TEDATAP,KWD+2 STORE ADDR OF KWD 




CALL 


$ INDEX, KWD, NEWOTEl+OTEDATAP, (NEW0TE3) ,2 




ENDIF 




* SET 


UP EXIT 






MOVEA 


(AMACDATA,#1), NEWOTE STORE OTE COUNT 




GOTO 


ENDTASK 




COPY 


COPCHECK COPY CODE FOR OPCHECK SUBRTN 




COPY 


C$INDEX COPY CODE FOR $INDEX SUBRTN 




ENDPROG 






END 








Figure 7-4. Sample Overlay Program 
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After you complete the coding of the overlay program, you must compile it using 
SEDXASM. You must create a load module by using either SUPDATE or 
J SEDXLINK. You must specify the name of the load module in a language control 

data set extension. How and why you do this is described in the section "Creating a 
Language Control Data Set Extension." 

Creating a Language Control Data Set Extension 

SEDXASM uses a language control data set to generate syntax error messages and 
to locate overlay programs. The $EDXL data set contains this information. You 
create an extension to $EDXL to contain your error messages and overlays. 
Creating an extension to $EDXL minimizes the changes you would have to make if 
you receive a new version of $EDXL or SEDXASM. 

A language control data set is divided into two logical parts. The first part contains 
the syntax error messages. The second part contains the names of overlay programs 
and instructions. Each overlay has a corresponding instruction which it processes. 
The second part also contains the names of the copy code modules that you might 
reference in an assembly. The extension you create has this same format. 

There are five control statements you can use in a language control data set. The 
following is a brief description of these control statements: 

*COMMENT Indicates a comment 

*COPYCOD Defines a copy code library 

*EXTLIB Defines a language control data set extension 

*OVERLAY Defines an overlay program and the instruction(s) it processes 

**STOP** Indicates the end of a language control data set. 

The format and description of the control statements are in the section "Control 
Statements" on page 7-15. 

This section shows how to create an extension for the NEWCMD instruction. You 
use a text editor to create the extension. 

Note: Once the language control data set has been modified, you must update it 
using the BUILD (BU) option of SEDXASM. 

Entering the Syntax Error Messages 

In the sample overlay program, four syntax messages were defined. The 
ASMERROR statement was used to indicate the message number (1 —4). The 
messages you enter in this data set and their hne numbers must correspond to the 
ASMERROR message numbers. 

You begin the message in column 2. The numbers you enter in columns 2 and 3 
indicate the completion code. SEDXASM does not generate object code if you 
specify a completion code greater than 8. 
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The messages for NEWCMD look like the following: 



08 *** INVALID OR UNDEFINED OPERATION CODE 



08 



AN INVALID POSITIONAL OPERAND WAS SPECIFIED 



08 *** AN INVALID KEYWORD PARAMETER WAS SPECIFIED 
08 *** OPERAND ONE IS MISSING 



Following the syntax messages, you must specify the overlay program and 
instruction names. 

Specifying tlie Overlay and Instruction Names 

You use the *OVERLAY statement to define the name of the overlay program, the 
volume it resides on, and the instruction(s) the overlay processes. This statement 
must begin in column 1 . 

Assuming the load module for the sample overlay program is in data set 
NEWOLAY on volume ASMLIB, the *OYERLAY statement would look Hke: 



08 


*** 


INVALID' OR 


UNDEFINED OPERATIOI^ 


CODE 


08 


*** 


AN INVALID 


POSITIONAL OPERAND 


WAS SPECIFIED 


08 


*** 


AN INVALID 


KEYWORD PARAMETER WAS SPECIFIED j 


08 


*** 


OPERAND ONE 


: IS MISSING 




*OVERLAY NEWOLAY ASMLIB NEWCMD 





You must enter a statement to indicate the end of the extension data set. You enter 
the **STOP** statement beginning in column I to do this. The complete extension 
data set now looks like: 



08 *** INVALID OR UNDEFINED OPERATION CODE 
08 *** AN INVALID POSITIONAL OPERAND WAS SPECIFIED 
08 *** AN INVALID KEYWORD PARAMETER WAS SPECIFIED 
08 *** OPERAND ONE IS MISSING 

*OVERLAY NEWOLAY ASMLIB NEWCMD 

**STOP** 



Because the name SEDXLUSR is specified on the ASMERROR statements in the 
overlay program, you must save the extension with that name. After you save the 
language control data set extension, you must specify its name and volume in 
$EDXL. You do this by editing $EDXL and entering an *EXTLIB statement 
beginning in column 1 . 



^"^ 
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An example of what $EDXL would look like with the *EXTLIB statement follows: 



08 *** yoo MANY POSITIONAL OPERANDS WERE SPECIFIED 
08 *** AN INVALID KEYWORD PARAMETER WAS SPECIFIED 
08 *** ONE OR MORE UNDEFINED LABELS WERE REFERENCED 



08 *** PART NOT ALLOWED WITH DSX SPECIFICATIONS 

*OVERLAY $ASM00O8 ASMLIB MOVE MOVEA AND I OR FOR 

*OVERLAY $ASM0009 ASMLIB WAIT POST ENQ DEQ 

*COMMENT 

*OVERLAY $ASNO0O3 ASMLIB PROGRAM LOAD DSCB 

*EXTLIB $EDXLUSR ASMLIB 

*COPYCOD ASMLIB 

*COPYCOD EDXG02 

**STOP** 



After you create the language control data set extension and update $EDXL, the 
next step is to add the operation code for NEWCMD. The procedure for doing this 
is described in "Defining the Instruction Operation Code" on page 7-17. 

Control Statements 

This section describes the control statements you can use in a language control data 
set. 

*OVERLAY Statement 

You use the *OVERLAY statement to define the name of the overlay program, the 
volume that it resides on, and the instructions that it processes. 

The *OVERLAY statement has the following format: 



Column 


Contents 


1-8 


♦OVERLAY 


10-17 


Program name 


19-24 


Volume name (blank indicates IPL volume) 


28-35 


Instruction 1 


37-44 


Instruction 2 


46-53 


Instruction 3 


55-62 


Instruction 4 


64-71 


Instruction 5. 



If an overlay program processes more than five instructions, you continue the 
instruction names in column 1 on the next line. You can specify up to eight 
instruction names on the continued line. Each instruction is allowed eight columns 
and one blank. Instructions would begin, for example, in columns 1, 10, and 19. 
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*EXTLIB Statement 

You use the *EXTLIB statement to define a language control data set extension. J'~^ 

This data set contains additional error message text, overlay and instruction names, ■ 1 

and copy code volume names. The extension data set has the same format and ^"""^ 

characteristics as the primary language control data set ($EDXL). 

The *EXTLIB statement has the following format: 

Column Contents 

1-7 *EXTLIB 

10 - 17 Language extension data set name 

19 — 24 Volume name (blank indicates the IPL volume). 

You should always insert this statement before any *COPYCOD statements in the 
primary language control data set. 

*COPYCOD Statement 

You use the *COPYCOD statement to define a copy code library. The volume you 
specify contains source code modules you reference on the compiler COPY 
statement. 

The *COPYCOD statement has the following format: 

Column Contents 
1-8 *COPYCOD 

10 - 17 Volume name. 

The language control data set or its extensions may contain up to five different ^^^ 

*COPYCOD statements. When $EDXASM processes compiler COPY statements, it r 

searches the defined *COPYCOD volumes in the order in which the *COPYCOD 
statements occur in the language control data set. 

^COMMENT Statement 

You use the *COMMENT statement to insert optional comments in the language 
control data set. $EDXASM ignores the text you specify on this statement. 

**STOP** Statement 

You use the **STOP** statement to indicate the end of the language control data 
set. You can add additional error messages, overlay programs, and copy code 
modules after this point. The number of additional modules is limited by the size of 
the operation code table (OPCTABLE). 



\j|| i||l7 



C, 
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Defining the Instruction Operation Code 



Every EDL instruction must have its operation code defined in the emulator 
command table. This section explains how you can define the operation code for 
NEWCMD through the use of an initialization routine. This routine will execute 
every time you IPL. 



The following code inserts the operation code into the emulator command table, 
explanation of this routine follows the example. 



An 





PROGRAM 


MAIN=NO 






COPY 


PROGEQU 


PROGRAM HDR EQUATES 




EXTRN 


INITEXIT,MYRTN 


DEFINE EXTERNAL ENTRY PTS 




ENTRY 


CMDINIT 




CMDINIT 


EQU 


* 






MOVE 


#1,$CMDTABL 


EMULATOR COMMAND TABLE 




MOVEA 


(2,#1),MYRTN 


DEFINE OP CODE 01 PROCESS RTN 




GOTO 


INITEXIT 


BRANCH TO SUPV INIT RTN 




ENDPR06 








END 







o 



The routine includes the PROGEQU equates. Doing this resolves references to 
$CMDTABL. SCMDTABL contains the addresses of the routines that do the 
processing for EDL instructions. Next, the routine defines two external entry points: 
INITEXIT and MYRTN. INITEXIT is an entry point in the supervisor to which 
your routine must return control upon exit. MYRTN is the entry point of the 
Series/ 1 assembler program that processes the NEWCMD instruction. This routine 
is described later. 



The code beginning at entry point CMDINIT places the address of MYRTN in the 
emulator command table. The MOVE instruction moves the starting address of the 
emulator command table ($CMDTABL) into software register 1 (#1). The MOVEA 
instruction moves the address of MYRTN two bytes into the table. Hence, when the 
emulator encounters operation code 01, the emulator passes control to MYRTN. 

Note: Operation codes 01 and 02 are reserved for your use. To define operation 
code 02, move the address of the routine four bytes into the emulator command 
table. 

You exit the routine by branching to label INITEXIT. 

You must assemble and Unk edit this routine with the supervisor. You specify the 
entry point name CMDINIT on the INITMOD = operand of the SYS? ARMS 
statement at system generation. 

The entry point MYRTN, defined as an external, must be the entry point of the 
routine that processes NEWCMD. The Series/ 1 assembler code required for this 
routine is described next. 
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Writing thie Assembler Code for NEWCI\/ID 



This section shows the Series/ 1 assembler code that performs the function of 
NEWCMD. For the instruction you create, you must also write the Series/ 1 
assembler code that performs the function you need. Refer to the IBM Series/ 1 
Event Driven Executive Macro Assembler, GC34-03I7 for details on how to code in 
Series/ 1 assembler. 

You will need the Series/1 Macro Assembler ($S1ASM) to perform this step. 

Coding Considerations 

When you code your Series/1 assembler routine, adhere to the following: 

• Write the routine in Series/ 1 assembler code only. 

• Follow the register conventions used by CMDSETUP. 

• Ensure the routine is reentrant: 

- No subroutines are used. 

- No parameter naming operands (Px = ) are coded. 

- Data areas are unique to each task. 

- Always test R5 for the operation code. 

- Ensure R2 contains the TCB address upon exit. 

- Ensure Rl is incremented by the instruction length (in bytes) upon exit. 

Description of Sample Program 

Again, if you code one operand on the NEWCMD instruction, it adds 1 to the value /(^ \ 

of operand 1 . If you code two operands, the value of operand 2 is added to the L J 

value of operand 1. The following description explains how this is done: 

At the entry point MYRTN, the routine begins by checking the flag bits of the 
operation code in register 5 (R5). The flag bits indicate whether one or two 
operands were specified. If bit 1 equals 1, only one operand was coded on 
NEWCMD. The routine branches to label OPNDl to process operand 1. Here, the 
routine adds the value 1 to the value of 

The code at label OPND2 is executed when bit 1 of the operation code equals 0. 
This bit indicates both operand 1 and operand 2 were coded. The value of 
operand 2 (R4) is added to the value of operand I (R3). Next, register 1 (Rl) is 
incremented by six bytes. After register 1 is incremented, the routine branches to 
CMDSETUP. 



C. 



1) 
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ENTRY 




MYRTN 




MYRTN 

* 


EQU 




* 




* CMDSETUP REGISTER CONVENTIONS: 




* 


Rl == 


=> 


OP CODE 




* 


R2 == 


=> 


TCB 




* 


R3 == 


=> 


OPl ADDRESS 




* 


R4 == 


=> 


0P2 ADDRESS OR 


DATA (IF IT EXISTS) 


* 
* 


R5 == 


=> 


OP CODE 




* 
CHKBITS 


TWI 




X" 4000 ',5 TEST 


IF BIT 1 OFF; IF OFF 


* 








THERE IS ONLY ONE OPERAND 




JOFF 




OPNDl 


LABEL FOR ONLY ONE OPERAND 


0PND2 


AW 




(R4),(R3) 


ADD-0P2 TO OPl 




AW I 




6,R1 


SET UP Rl FOR NEXT INSTRUCTION 




BX 




CMDSETUP 


BRANCH BACK TO EMULATOR 


OPNDl 


EQU 




* 






AW I 




1,(R3) 


ADD 1 TO OPl 




AW I 




4,R1 


SET UP Rl FOR NEXT INSTRUCTION 




BX 




CMDSETUP 


BRANCH BACK TO EMULATOR 




END 









grny^ 



Use SSIASM to assemble this routine. You must link edit the assembled output 
from this routine and the output from the initialization routine with the supervisor. 



Testing the New Instruction 



To verify that the overlay program, initiahzation, and assembler routines work 
properly, write a small program containing the new instructions, for testing 
purposes. 



System Generation Requirements 

Before you test the instruction: 



1 . Use a text editor to read in the Hnk-control data set that defines the modules 
currently in your supervisor (normally LINKCNTL on EDX002). 

2. Specify INCLUDE statements for the assembled output from the initialization 
routine and the assembler routine. You specify the names of these data sets. 

3. Write (save) the updated hnk-control data set back to LINKCNTL. 

4. Use a text editor to read in the data set that defines your current system 
configuration (normally SEDXDEFS on EDX002). 

5. Code the INITMOD= operand on the SYSPARMS statement. You must 
specify the entry point name of your initiahzation routine. For the NEWCMD 
instruction, specify the entry point name CMDINIT. 
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6. Write (save) the updated data set back to SEDXDEFS. 

7. Perform a system generation. 

8. After the system generation completes, initialize (II command of SINITDSK) the 
new supervisor and IPL the system. 

When you complete these steps, you can test your instruction. 

Coding a Test Program 

When you test the instruction, you should code all the possible variations of the 
instruction's syntax. You should also test for invaUd syntax. 

You can use the following sample program to test the NEWCMD instruction: 



TEST 


PROGRAM 


BEGIN 




BEGIN 


EQU 


* 






NEWCMD 


A 


ADD 1 TO A (1) 




NEWCMD 


A,KWD=B 


ADD B (2) TO A (2) 




PRINTEXT 


■eTHE RESULT IS: 


1 




PRINTNUM 


A 


A = 4 




MOVEA 


#1, VALUES 


SET UP INDEX 




NEWCMD 


C,KWD=(4,#1) 


ADD D (5) TO C (3) 




PRINTEXT 


'@THE RESULT IS: 


1 




PRINTNUM 


C 


C = 8 




MOVEA 


AY,X 


SET ADDR OF X 




NEWCMD 


A,P1=AY 


USE X AND ADD 1 




PRINTEXT 


'0THE RESULT IS: 


1 


* 


PRINTNUM 


X 


X = 1 


* INVALID SYNTAX - 
* 


THESE GENERATE ERROR MESSAGES 




NEWCMD 


X,KWDD 




* 


NEWCMD 


X,P2=ERR 




* 


PROGSTOP 






A 


DATA 


FT 




VALUES 


EQU 


* 




B 


DATA 


F'2' 




C 


DATA 


F'3' 




D 


DATA 


F'5' 




X 


DATA 

ENDPROG 

END 


F'O' 





V^' 



If the overlay program is correct, the compiler listing for the test program will show 
the object code generated for the vahd statements. Further, SEDXASM should issue 
error messages for the statements with invahd syntax. 

Upon receiving a — 1 completion code from $EDXASM, create a load module using 
SUFDATE or SEDXLINK. Load the program with the $L command to execute the 
program. The output from your program should yield the expected results. 






7-20 SC34-0942 



Creating Your Own EDL Instruction 






Debugging Overlay Programs 

You can use $DEBUG to debug an overlay program. To do this, you must: 

1. Code a READTEXT, QUESTION, or WAIT KEY instruction as the first 
executable instruction of the overlay program. When the overlay program is 
loaded, it will stop at this instruction and wait for input from the terminal. 

2. Load SEDXASM and specify one overlay area (OV option) when you compile 
the source program containing your new EDL instruction. 

3. Load $DEBUG in the same partition as SEDXASM when SEDXASM loads 
your overlay program and the overlay program stops at the READTEXT, 
QUESTION, or WAIT KEY. 

4. Enter SASMOPCD when SDEBUG prompts you for the program name. If 
SASMOPCD is already in storage, do not request a new copy to be loaded. 

Once the overlay program is in storage, you can examine data areas and set 
breakpoints with SDEBUG. 

If a program check occurs in the overlay program, the system cancels the overlay 
program and issues a program check message. The error message may not give the 
correct displacement into the overlay program for the failing instruction (Rl) and 
the TCB address (R2). If these addresses appear to be outside the program, you can 
calculate the correct addresses by subtracting the program load point address from 
the address of Rl and R2. The resulting addresses may be in either SEDXASM or 
in one of the overlay programs. 



Creating Unique Labels Within the Overlay Program 

Instructions may require unique labels which do not conflict with labels you create 
from a previous call to your overlay program or labels define in an application 
program. For example, SEDXASM creates a unique label (internally) for each 
ENDIF statement when multiple IF-ENDIF statements are coded in a program. 

SEDXASM provides a method for you to create unique labels when you use the field 
SSYSNDX in an overlay program. SSYSNDX is a 1-word field in the compiler 
common area. You reference this field through the ASMCOMM equates. 

SEDXASM sets up a 4-digit counter for this field. You must add 1 to this counter 
to generate a unique label each time you use SSYSNDX. You can convert the 
binary value of SSYSNDX to a 4-character EBCDIC representation of the number 
using the CONVTB instruction. The following example shows how to convert the 
value of SSYSNDX. Assume that #1 points to the compiler common area and that 
SSYSNDX contains the value 2. After the conversion, INDEX contains the 
character value "0002." 





CONVTB 

• 


INDEX, (SSYSNDX, #1),F0RMAT=(4, 0,1) 


INDEX 


• 
DC 


CL4'0O00' 
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After conversion, you append the four characters to a 1-4 character prefix to form 
a unique label. For example, the following code shows how to define a unique label 
with the prefix $$LI using the value in INDEX from the previous example: 





• 






• 






• 






MOVE 


LABl+4, INDEX, (4, BYTES) 




ADD 

• 


($SYSNDX,#1),1 


OTEl 


• 
OTE 


TYPE=ADDRESS,SLENAME=SLE1 


SLEl 


SLE 


ADDRESS=LAB1,LENGTH=8 


LABI 


DC 


CL8'$$Lr 


INDEX 


DC 


CL4'0O0O' 



The name on the label created would have the text $$LI0002. 
to this label in other object text elements. 



You could then refer 



Generating Source Statements 



An overlay program can generate one source statement which SEDXASM processes 
after the generating overlay ends. $EDXASM processes this source statement before 
processing the next statement in the source data set. One instance where this feature 
is used, is when you specify TASK = YES on a DISK statement. The overlay 
program SASMOOOS, which processes the DISK statement, creates a TASK 
statement for the device's disk task. The overlay program SASMOOOT, which 
processes the TERMINAL statement, also uses this feature to generate keyboard 
tasks for terminals. 



o 



You can use this feature in your overlay program to generate a source statement and 
optionally create a continuation line for that statement. 

Notes: 

1 . If you built an instruction in the overlay program, the source statement must 
also be an instruction. If you built a statement in the overlay program, the 
source statement must also be a statement (nonexecutable). 

2. The source statement you create does not appear in the compiler hsting; 
however, the object code generated does appear if the source statement is an 
instruction. 

3. If a compilation error occurs with the source statement you create, the error 
message appears after the instruction or statement you built in the overlay 
program. 
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Creating a Source Statement — No Continuation Line 

To create a source statement (with no continuation line), do the following: 

1 . Define an 80-byte area in the overlay program which contains the text of the 
source statement. For example, the following statement: 



TRMNL 



lOCB 



SCREEN=ROLL 



looks as follows when defined in the overlay program: 



SRCSTMT DATA 



CL80' TRMNL 



lOCB 



SCREEN=ROLL' 



Move the field #AINBUF to a software register. This field is defined in 
ASMCOMM and contains an address of a storage area. The address to which 
#AINBUF is pointing is where you move the source statement. For example, if 
#1 points to ASMCOMM, the following code shows what you must do to move 
the source statement to #2: 



o 



MOVE #2,(#AINBUF,#1) 

MOVE (0, #2), SRCSTMT, (80, BYTES) 



GET ADDR OF STORAGE AREA 
MOVE SOURCE STATEMENT 



Move the value X'FFFF' to #AINBUF. This move indicates that the overlay 
program is creating a source statement and that $EDXASM must process it 
before the next statement in the source data set. After moving X ' FFFF ' to 
#AINBUF, store the number of object text elements created in the overlay, and 
return control to label ENDTASK to exit the overlay program. The following 
example shows how to set #AINBUF and exit the overlay program: 



MOVE (#AINBUF,#1),'FFFF' 

MOVEA (AMACDATA,#1),NEW0TE 

GOTO ENDTASK 



GENERATE SOURCE FLAG 
PASS OTE COUNT 
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Creating a Source Statement — With Continuation Line 

To create a source statement with a continuation line, you do the same steps 
previously discussed plus some additional steps. These additional steps are explained 
in this section. 



o 



After you define the source statement within the 80-byte area, do the following: 

1 . Insert a nonblank character in column 72 of the source statement. 

2. Move the address, to column 77 of the source statement, of a subroutine that 
will append the continuation Une to the source statement. 

The subroutine, which you must write and define in the overlay program, must be 
written to receive the address of a storage area. SEDXASM calls the subroutine 
{after the overlay program branches to ENDTASK) and passes the subroutine an 
address. Because SEDXASM defines the storage area for you, do not define this 
area in the overlay program. The subroutine must use the buffer area at that 
address to construct the continued source statement. 

The following is an example of how you can do this: 





• 
• 
• 
MOVE 


#2,(#AINBUF,#1) 


GET ADDR OF STORAGE AREA 




MOVE 


(0, #2), SRCSTMT, (80, BYTES) 


MOVE SOURCE STATEMENT 




MOVE 


(71,#2),C'X',(1,BYTE) 


SET CONTINUATION FLAG 




MOVEA 


(76,#2),C0NTSUB 


MOVE ADDR OF SUBRTN 




MOVE 


(#AINBUF,#1),'FFFF' 


GENERATE SOURCE FLAG 




MOVEA 


(AMACDATA,#1),NEW0TE 


PASS OTE COUNT 




GOTO 


ENDTASK 




SRCSTMT 


DATA 


CLSO'TRMNL lOCB SCREEN 


=ROLL,' 


CONTSRC 


DATA 


CL80'PAGSIZE=6O,NHIST=6' 




CONTSAVE 


DATA 


F'O' 


SAVE AREA ADDR 




SUBROUT 


CONTSUB,CONTBUF 






MOVE 


CONTSAVE, #2 


SAVE CONTENTS OF #2 




MOVE 


#2,C0NTBUF 


GET BUFFER ADDR 




MOVE 


(0,#2),C' ',(80, BYTES) 


SET BUFFER TO BLANKS 




MOVE 


(15,#2), CONTSRC, (18, BYTES) 


BUILD NEXT LINE 




MOVE 


(71, #2), C ■,(1,BYTE) 


CLEAR CONTINUE COLUMN 




MOVE 


#2, CONTSAVE 


RESTORE #2 




RETURN 










J 



The source statement created in the previous example and passed to SEDXASM 
looks like the following: 



TRMNL lOCB SCREEN=ROLL, 

PAGSIZE=60,NHIST=6 
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Overlay Program Statements 



This section describes in detail the overlay program statements you can use and their 
coding syntax. 



$IDEF Statement — Build Model EDL Instruction 

You use the $IDEF statement to build a model of the instruction. When you code 
$IDEF, you specify the positional operands and keywords of the instruction. The 
number of positional and keyword operands for an instruction must not exceed 50. 

You can optionally specify error exits on $IDEF for invahd syntax. These error 
exits are used in conjunction with the ASMERROR statement. 

The following is the syntax for the SIDEF statement: 

Syntax: 



posits,kwds,PERR = ,KERR = 



label $IDEF 

Required: none 

Defaults: PERR = INVALPOS,KERR = INVALKWD 

Indexable: none 



Operand Description 

posits The Ust of allowable positional operands. 

kwds The list of allowable keyword operands. The keywords can be 1 — 7 

characters in length. The keyword you specify is the actual keyword 
coded for the new instruction. 

PERR = The label of an instruction to branch to if more positional operands 

are coded in the instruction than defined by the instruction model. If 
omitted, control is passed to label INVALPOS, which you must code. 

KERR = The label of an instruction to branch to if a keyword operand is coded 
in the instruction which is not listed in the instruction model. If 
omitted, control is passed to label INVALKWD, which you must 
code. 



Examples of $IDEF 



The following are examples of how to code the SIDEF statement: 



MODELl $IDEF 
M0DEL2 $IDEF 
M0DEL3 $IDEF 



(P0S1,P0S2),KWD 

POS, (MODE, LINE, SKIP, SPACES) 

POS , KWD , PERR=BADPOS , KERR=BADKWD 
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ASMERROR Statement — Generate Syntax Error Messages 

The ASMERROR statement generates a syntax error message for the input 
statement currently being processed if you code that statement incorrectly. 
ASMERROR is used in conjunction with the $IDEF statement. SEDXASM passes 
control to the label ENDTASK after the message is issued. 

Note: A control block is required in the overlay program for you to use 
ASMERROR statement. You create the control block by coding: 



ASMERROR GENERATE 



You code ASMERROR GENERATE only once in a program. 
Syntax: 



label 
Required: 
Defaults: 
Indexable: 



ASMERROR 

number 

extlib - $EDXL 

none 



number.extlib.Pl = 



Operand Description 

number Code a decimal number representing the error message number to be 

generated. This number corresponds to a hne number in the language 
control data set ($EDXL or extension). If this number is greater than 
the maximum error text line number, the system issues a general error 
message. 

extlib The data set $EDXL or the name of the language control data set 

extension in which the error message text is located. This name must 
correspond to the data set name on an *EXTLIB control entry when 
you load $EDXASM. If the specified data set is not included as an 
extension to the primary language control data set ($EDXL), a general 
error message with asterisks for the data set name is printed. This 
data set is not used for an error message in the primary language 
control data set. 



^'<_y 



Examples of ASMERROR 

The following are examples of the ASMERROR statement: 



INVALPOS ASMERROR 

INVALKWD ASMERROR 

ASMERROR 



1 
2 
17,$EDXLUSR 



Note: You can use the first two examples for the default error exits on the $IDEF 
statement. Messages 1 and 2 produce messages appropriate to these errors. 
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OTE Statement — Build Object Text Element 

The OTE statement defines an object text element. You can use an object text 
element to do the following: 

• Define a label 

• Generate one or more bytes of object code 

• Generate error messages 

• Define external references and entry points. 

The compiler aUgns the object code on an even-byte address for TYPE = OPCODE, 
ADDRESS, and FCON. 

Syntax: 



label 


OTE TYPE = ,DUPFAC = ,SLEDATA = 


,SLENAME = 


Required: 


TYPE = 




Defaults: 


DUPFAC = 1,SLEDATA = 0,SLENAME = 




Indexable: 


none 











operand Description 

TYPE = The type of object text element to be defined. The ASMCOMM 

equate field OTETYPE defines this operand. The following types are 
vahd: 

NULL OTE is to be ignored. 

OPCODE Data is an operation code. The SLED ATA operand 

contains the 2-byte operation code. 

ADDRESS Data is an address. The SLED ATA operand must 

point to the subHst element (SLE) defining the address 
constant. 

ERROR Generate an error message. The SLED ATA operand 

defines the numerical error message to be printed. 
This number corresponds to a line number in the 
primary language control data set ($EDXL). 

FCON Data is a fullword constant. The SLED ATA operand 

contains the two bytes of data to be generated. 

DATA Define untranslated data. The SLED ATA operand 

must point to a sublist element defining the data. 

EQUATE A label at the current location counter (for example 

LOCI EQU *). The SLENAME operand must point 
to the SLE of the label. The SLED ATA operand 
should point to an SLE which points to the asterisk. 
Note that if you require an equate for other purposes, 
you can use the LABELS subroutine. 

EXTRN An external reference. The SLEDATA operand 

points to the SLE defining the name of the external 
symbol. 
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WXTRN 



ENTRY 



A weak external reference. The SLED AT A operand 
points to the SLE defining the name of the external 
symbol. 

An entry point. The SLEDATA operand points to 
the SLE defining the symbol 'vvhich is to be an entry 
Doint. 



DUPFAC = 



SLEDATA = 



SLENAME = 



Specifies the dupHcation factor for the object text element, or the 
number of times SEDXASM is to duphcate the object text in the 
object file. Only the first byte of text has the label defined by 
SLENAME. 

You use this operand primarily for duphcating data definition fields, 
for example 128F'0' 

If you specify DUPFAC = 0, SEDXASM does not generate object text, 
but does align boundaries. This is equivalent to coding: 

ALIGN WORD 

The ASMCOMM equate field OTEDATAC defines this operand. 

If TYPE = OPCODE or FCON, SLEDATA defines the data to be 
entered into the object file. If TYPE = ERROR, it defines the error 
message number to be printed. If TYPE = ADDRESS, DATA, 
EXTRN, WXTRN, or ENTRY, it must contain the address of the 
sublist element (SLE) defining the data to be processed. 

The ASMCOMM equate field OTEDATAP defines this operand. 

The label assigned to the first byte of object text generated by the 
current OTE. If this field contains a 0, no label is assigned. 
Otherwise, it must contain the address of the SLE defining the label to 
be defined. 

The ASMCOMM equate field OTEDATAL defines this operand. 






Examples of OTE 



The following are examples of the OTE statement: 



OTEl OTE TYPE=ADDRESS 

OTE TYPE=FCON,SLEDAT/\=0 

OTE TYPE=EXTRN,SLEDATA=SLE1 
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SLE Statement — Build Sublist Element 

The SLE statement enables you to define a sublist element in the same format as a 
subhst element generated by SEDXASM. You must use the SLE statement to 
generate a label or a data string that does not appear in the original input data. 



Syntax: 



label SLE ADDRESS = , LENGTH = , TYPE 

Required: ADDRESS = ,LENGTH = 

Defaults: TYPE = (address) 

Indexable: none 



Operand Description 

ADDRESS = The address of the text string defining the data. The ASMCOMM 
equate field SLEDATA defines this operand. 

LENGTH = The number of characters in the text string. The ASMCOMM equate 
field SLELENG defines this operand. 

TYPE = Omit this operand if the data defines an address; otherwise, specify 

either SELFDEF or STRING. The ASMCOMM equate field 
SLELENG defines this operand. 

SELFDEF Specify a self-defining term (for example, decimal or 
hexadecimal constants). 

STRING Specify string data. You must process this data by 
coding an OTE with TYPE = DATA specified. 



Examples of SLE 



The following are examples of the SLE statement: 



SLEl 


SLE 


ADDRESS=NAME1,LENGTH=3 


SLE2 


SLE 


ADDRESS=NAME2 , LENGTH=1 ,TYPE=SELFDEF 


SLE3 


SLE 


ADDRESS=ASTERISK, LENGTH=1 


NAMEl 


DC 


CL3'XYZ' label XYZ 


NAME2 


DC 


CLl'5' constant 5 


ASTERISK DC 


CLl'*' current location counter 
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Overlay Program Subroutines 

This section describes in detail the overiay program subroutines you can use and 
their coding syntax. 

$INDEX Subroutine — Indicate Index Register Usage 

The SINDEX subroutine examines an operand field for index register specification. 
It also stores control infi^rmation in the operation code word and in the object text 
element for the operand being processed. 

The SINDEX subroutine is in the form of copy code. You must include a COPY 
C$INDEX statement in your program to use it. 

The CALL to the SINDEX subroutine has the following syntax: 

Syntax: 



label CALL $INDEX,ole,opword,ote,posit 



Operand 
$INDEX 
ole 

opword 

ote 

posit 



Description 

Code SINDEX as the first operand on the CALL instruction. 

The address of the operand list element (OLE) of the operand being 
processed. 

The address of the operation code word into which index register usage 
indicators may be set. 

The address of the object text element (OTE) that indicates the type of 
input. 

The position number (1, 2, or 3) of the input operand on the source 
statement. 






Entry Conditions 



You must store the SLE address of the operand being processed in the appropriate 
OTE before you call SINDEX. 



^*«i>^ 
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Exit Conditions 






Registers Used 



How the "ole" operand is presented to $INDEX determines how the register flag 
bits are set in "opword." The flag bit settings are shown in Figure 7-5. 



Bits/Operand 


Register 
Not Used 


#1 Used 

as (x,#l) 


#2 Used 

as (x,#2) 


#1 or #2 
Used as 
Operand 


6 & 7 for opl 


00 


01 


10 


11 


4 «fe 5 for op2 


00 


01 


10 


11 


2 & 3 for op3 


00 


01 


10 


11 



Figure 7-5. Register Flag Bits from $INDEX 

Error message No. 4 is issued if the number of operand sublist elements is not 1 or 
2. Error message No. 5 is issued if an index register other than #1 or #2 is specified. 



Software register #2 is used. 






BLDTXT Subroutine — Build Object Text 

The BLDTXT subroutine builds object text based on a list of object text elements 
(OTEs). You use the GTE statement to build the object text element. 

The BLDTXT subroutine is in the form of copy code. You must include a COPY 
CBLDTXT statement in your program to use it. 

The CALL to the BLDTXT subroutine has the following syntax: 

Syntax: 



label 



CALL 



BLDTXT 



Entry Conditions 



Exit Conditions 



^bT 



Operand Description 

BLDTXT Code BLDTXT as the operand on the CALL instruction. 



The AMACDATA field in compiler common area must point to a 1-word count of 
the number of object text elements. You must include the ASMCOMM equates in 
your program to access the compiler common area. The AMACDATA field must 
be followed by the object text elements. The length of each OTE is defined by the 
equate LOTE. 



None 
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Registers Used 



None 



GETVAL Subroutine — Evaluate Character String 

The GETVAL subroutine evaluates a character string which is a self-defining term. 
A self-defining term is a fixed-decimal constant, a hexadecimal constant, or a 1- or 
2-byte EBCDIC character string. 

Examples of data handled by GETVAL: 

• Decimal constants 1, 100, -300, 32767, -12345 

• Hexadecimal constants X ' 12 ' , X ' ABCD ' , X ' FFFF ' , X ' 1' 

• EBCDIC constants C'A', C'XY', C'Ol', C'E' 

The GETVAL subroutine is in the form of copy code. You must include a COPY 
CGETVAL statement in your program to use it. 

The CALL to the GETVAL subroutine has the following syntax: 

Syntax: 






label CALL GETVAL,sle,value,errexit 



Operand Description 

GETVAL Code GETVAL as the first operand on the CALL instrucfion. 

sle The address of the subUst element (SLE) which points to the string to 

be evaluated. 

value A word to receive the result of the evaluation. 

errexit The address of an error routine to be branched to if invalid syntax is 

encountered in the evaluation. 






Entry Conditions 
Exit Conditions 



None 



If an error exit is taken, "value" contains the result computed at the time of the 
error. For example, if the string 123X is evaluated, the result at the time of the 
error exit is 123. 
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LABELS Subroutine — Define or Resolve Labels 

You use the LABELS subroutine to define or resolve a label for a sublist element 
(SLE). You can define or resolve the following label types: 

ADDRESS 

EQUATE 

EXTRN 

WXTRN 

ENTRY. 

The LABELS subroutine is in the form of copy code. You must include a COPY 
CLABELS statement in your program to use it. 

You code the CALL for the LABELS subroutine differently for label definition and 
label resolution. 



Defining Labels 



The CALL for the LABELS subroutine for label definition puts the label you define 
into the symbol table with the type and value you specify. 

The CALL to the LABELS subroutine for label definition has the following syntax: 

Syntax: 






label CALL LABELS,#value,#type,l 



Operand Description 

LABELS Code LABELS as the first operand on the CALL instruction. 

#value The address of the label value to be put into the symbol table. 

#type Label type to be put into the symbol table. 

1 Indicates label definition. 
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Resolving Labels 



If you call the LABELS subroutine to resolve a label and the label is defined, the 
label type and value are returned in #type and #value, respectively. If the label is 
undefined, an entry is made in the symbol table, and type and value are set to in 
the symbol table. The #type operand is set to 0, and #value is set to the symbol 
table pointer index for the symbol. 

The CALL for the LABELS subroutine for label resolution has the following syntax: 

Syntax: 



label CALL LABELS ,#value,#type,0 



Entry Conditions 
Exit Conditions 



Registers Used 



Operand Description 

LABELS Code LABELS as the first operand on the CALL instruction. 

#value The label value is returned here if label is defined; otherwise, the 

symbol table pointer index for the symbol is returned. 

#type The label type is returned here if label is defined; otherwise, a zero is 

returned. 

Indicates label resolution. 



Software register #1 must point to the SLE of the label to be processed. 



If a duplicate symbol is encountered in label definition, an error message is issued. 
You reference the error message number through the #ERRMSG field in the 
compiler common area. You must include the ASMCOMM equates to refer to this 
field. 



None 






o 
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MOVEBYTE Subroutine — Move a Byte String 

The MOVEBYTE subroutine moves a variable-length byte string to a target location 
and right pads with blanks. 

The MOVEBYTE subroutine is in the form of copy code. You must include a 
COPY MOVEBYTE statement in your program to use it. 

The CALL to the MOVEBYTE subroutine has the following syntax: 

Syntax: 



label CALL MOVEBYTE,fromsle,toaddr,count 



Entry Conditions 



Operand 

MOVEBYTE 

fromsle 

toaddr 

count 

None 



Description 

Code MOVEBYTE as the first operand on the CALL instruction. 

The address of the sublist element (SLE) defining the source data. 

The address of the target location. 

The size of the target field. 



Exit Conditions 



If the number of characters in the SLE is greater than "count", control is passed to 
ASMERROR. If "fromsle" or the number of characters in the SLE equals zero, the 
target field is filled with blanks. 



Registers Used 



None 
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OPCHECK Subroutine — Check Statement Syntax 

You use the OPCHECK subroutine for source statement syntax checking. 
OPCHECK does the following: 

• Compares the number of positional operands in the source statement against the 
allowable number of positional operands. 

• Matches keywords specified in the source against the allowable keywords. 

• Stores the operand Hst element (OLE) and subhst element (SLE) addresses in the 
$IDEF expansion for each operand coded in the source statement. 

The OPCHECK subroutine is in the form of copy code. You must include a COPY 
COPCHECK statement in your program to use it. 

The CALL to the OPCHECK subroutine has the following syntax: 

Syntax: 






label CALL OPCHECK,(oplist) 



Entry Conditions 
Exit Conditions 



Operand Description 

OPCHECK Code OPCHECK as the first operand on the CALL instruction. 

oplist The oplist operand is the label on a $IDEF statement defining the 

model for an instruction. 



None 



Each positional and keyword operand specified in the source statement has its entry 
in the $IDEF expansion filled in with its OLE and SLE address. If the operand is 
missing, the corresponding entry in $IDEF is 0. 

If an invaUd number of positional operands is coded, control passes to the error exit 
for positional operand errors. This is the label specified (or default) for PERR = on 
$IDEF. If an invahd keyword is coded, control passes to the error exit for keyword 
operand errors. This is the label specified (or default) for KERR= on $IDEF. 



Registers Used 



Software register #2 is used. 
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SLPARSE Subroutine — Parse Input String 

The SLPARSE subroutine divides (parses) an input string into one or more sublist 
elements (SLEs). The SLEs are separated by commas. 

The CALL to the SLPARSE subroutine has the following syntax: 

Syntax: 



label CALL SLPARSE,ops,opl,optbl,tblng,n 



Operand Description 

SLPARSE Code SLPARSE as the first operand on the CALL instruction. 

ops The address of the input string. 

opl The number of characters in the input string. 

optbl The address of the output table to receive the results of the parse 
routine. 

tblng The length of the table (in bytes) to be generated. 

n The address of an area to receive the number of elements found. 



o 



Entry Conditions 



Exit Conditions 



None 



The value of the "n" operand is negative if unbalanced parentheses are encountered 
in the input string. 



Registers Used 



None 
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Chapter 8. Techniques for Improving Performance 

This chapter describes some of the techniques you can use to increase Series/ 1 
performance. 



Analyzing System Performance 






You can use the following utilities to identify the major performance areas in your 
system and to monitor any modifications you make to improve that performance. 

• CPU Monitor— the SCPUMON utility monitors the system's CPU utilization 
and displays the current data at a terminal in user specified intervals. The 
SCPUPRT utihty generates a CPU utilization report for a user-defined portion 
of the calendar year. The printed report shows daily CPU utihzation. 

• Disk Trace Utility— the SDSKMON utihty collects data on disk I/O activities 
and displays the data at a terminal. The SDSKMON utihty uses two utihty 
programs to print the statistics reports. The SDSKPRTl program hsts the 
user-specified operations recorded during the monitoring period. The 
$DSKPRT2 program produces two reports and an optional graphical 
representation of the disk I/O activity for a specific disk device. 

• EDX Performance Analyzer— the $S1PSYS utility monitors the system's use of 
I/O resources. SSIPSYS can track all task dispatches, I/O interrupts, and wait 
states. The SSIPSYSR utihty prints the system performance report from the 
SSIPSYS data set. The SSIPPRG utility monitors and analyzes the resources 
used within a program. The $S1PPRGR utihty prints the program performance 
report. 

Note: Refer to the Operator Commands and Utilities Reference for information on 
how to use these utilities and examples of the reports printed. The numbers that 
appear in the reports that these utihties generate are not necessarily exact. For this 
reason, you should use performance analysis as a relative measure of performance. 

Once you have identified the performance problems, you can use the information 
you gathered with the utilities to improve your system's performance. Improving 
performance may be as simple as finding and ehminating the one major bottleneck 
on your system. However, you may find that you need a detailed analysis, extensive 
reprogramming, or even a change to the architecture of your system. Therefore, you 
must have a thorough understanding of the application you are monitoring. 
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Setting Up Controls 

When you use performance tuning, you must establish a "control" group. Then you 
can determine if your efforts are actually improving the performance of your system. 

For example, if you have a transaction-based system, you can set up a control group 
of ten transactions of a particular type. Using the Performance Analyzer or the 
Disk Trace Utility, you would then monitor the group for data set access speeds, 
response times, and number of disk I/O operations. Then each time you change 
something on your system, monitor the same group to see what effect those changes 
made. 

Analyzing System Reports 

You can use the various reports generated by the SSIPSYSR, $DSKPRT1, and 
$DSKPRT2 utiUties and change your system accordingly. 

1. Analyze the reports generated by SSIPSYSR and SDSKPRTl to determine the 
volume which has the most disk activity. Put that volume in the center of the 
disk. Put the next most heavily used volume on one side and the third most 
heavily used volume on the other side, and so on. 

For instance, you normally allocate volume EDX002 first after initializing a 
disk, but in most cases you use this volume more heavily than any other. To 
improve access time, place this volume in the center of the disk as follows: 

a. Before allocating EDX002, allocate a volume that is one half the size of 
your disk. 

b. Allocate EDX002. (You might also consider making this volume large 
enough to hold the required system modules only.) 

c. Delete the volume you allocated initially. 

You can also use the reports to analyze data set activity. Then you can 
rearrange the data sets on each volume so that the most heavily used data sets 
are side by side. If the average time required to access data sets on one volume 
is significantly higher than on another volume, you may have initialized the disk 
with "write verify" on. Write verify doubles the time required for each write 
operation. 

If your system contains more than one disk drive, analyze the reports generated 
by SSIPSYSR and $DSKPRT1 to determine the volume which has the most 
disk activity. Place the most heavily used volume in the center of one disk drive, 
the second most heavily used volume in the center of another disk drive, and so 
on. You can also place your program-type data sets on one drive and your 
data-type data sets on another. 



o 



\.J 
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2. Instead of putting all your application programs and data sets on your IPL 
volume, you can improve directory search time by keeping only EDX functions 
on that volume. Create a separate volume for your application programs, 
another for application job streams, another for menus, and as many as you 
need for data. 

3. You can make all your volumes "performance" volumes to achieve the best 
processing speeds. The Data Set Summary Report contains the number of 
attempts the system made to open volumes other than performance volumes. 
Under the totals for each volume is a reference to a volume name $$DDyy (yy is 
the device address) and a data set $$. If the system accesses only performance 
volumes, $$ does not appear on the report. If it does appear, you know that the 
system is accessing nonperformance volumes. The number of times $$ appears is 
an indication of your performance degradation. 

You can use the Data Set Sxmmiary Report or the summary log from the 
$CPUMON utility to determine the frequency of program loads. Every time you 
load an appUcation program, the system reads $LOADER into storage. If you place 
SLOADER and executable programs onto a volume in unmapped storage (created 
with the SMEMDISK utiUty), you can reduce your load times as described in 
"Reducing Program Load Time" on page 8-7. 



Gaining Faster Access to Data Sets 



Whenever you reference a data set on a volxmie, the system searches the data set 
directory to find the location of that data set on the volimie. Assume the volume 
has several hundred data sets and the data set you need is near the end of the 
directory. The system has to read each data set directory entry until it finds the data 
set you need. This searching requires processor time. You can, however, reduce the 
amount of time it takes the system to search the directory. You do this by arranging 
the directory to have the frequently used data sets placed at the beginning of the 
directory. You can use the SDIRECT utility (explained in the Operator Commands 
and Utilities Reference) to arrange data sets in the directory. 



Gaining Faster Access to Volumes 

Several factors can determine how fast the system can access a volume: 



The order in which you define your DISK statements at system generation 
Whether you define a volume as a "performance" volume 
Whether you define a fixed-head volume on a fixed-head disk. 
Whether you define the volume on a memory disk. 
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Defining DISK Statements 

When you define DISK statements at system generation, you should always define 
{first) the device containing volumes you access frequently. 

Each device has a volume descriptor entry (VDE) and the VDEs are chained in the 
order you define the DISK statements. Therefore, the system has to read through 
the VDE chain to locate a volume. If the volume you need resides on the first disk 
device you define, the system only has to read the first VDE in the chain. 

Specifying Performance Volumes 

The system can access a volume designated as a "performance" volume faster than a 
"nonperformance" volume. You specify performance volumes by coding the 
VOLNAME = operand on the DISK or TAPE statements at system generation. 

Specifying performance volumes saves time because the system records the address of 
the volume in the volume descriptor entry (VDE) for that device at IPL time. For 
nonperformance volumes, the system records the volume address in the volume 
descriptor entry when you load the program. 

A volume designated as a performance volume requires an additional 46 bytes in the 
supervisor. 

Specifying a Fixed-Head Volume 

If you have a fixed-head disk, you should always allocate in the fixed-head area the 

volume you use most frequently. Because no "disk seek" operations are required on 

a fixed-head disk, the system can access directly the volume you need. /f'"^ 

Analyze the report generated by $DSKPRT2 to determine that the largest number of 
"disk seek" operations occurs at seek*distance 0. 

You allocate a fixed-head volume by using the $INITDSK utility (AF command). 
You can allocate one volume in the fixed-head area of the device. 

Defining a Memory Disk Volume 

The SMEMDISK utihty enables you to use unmapped storage as a disk. You can 
allocate up to six memory volumes in unmapped storage. The size of each volume is 
Hmited only by the unmapped storage available. By placing data or programs on 
these volumes, you can reduce access time. Keep in mind, however, that the volumes 
created by SMEMDISK are in main memory. Therefore, you will lose these 
volumes in the event of a power failure or an IPL. 
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Improving Disk and Tape I/O Performance 



You can increase performance for disk and tape I/O operations by coding 
TASK = YES on each DISK and TAPE statement at system generation. This causes 
each device to have its own task to service I/O requests as opposed to one task 
servicing all I/O requests for devices of the same type. 

Each DISK or TAPE statement with TASK = YES specified requires an additional 
128 bytes in the supervisor. 

You can improve I/O performance by using SMEMDISK to allocate all or a portion 
of unmapped storage to use as a "disk." By placing temporary work data sets on 
volumes in unmapped storage, you can reduce the amount of time required to access 
work data sets. 

You can allocate up to six memory volumes in unmapped storage. The size of each 
volume is hmited only by the amount of unmapped storage available. But volumes 
allocated in unmapped storage are part of main memory. Therefore, you will lose 
these volumes in the event of a power failure or an IPL. Use volumes you create 
with SMEMDISK only for work data sets, programs, and other files that you can 
recover if a power failure or IPL does occur. See "Reducing Program Load Time" 
on page 8-7 for tips on reducing program load times with SMEMDISK. The 
Operator Commands and Utilities Reference describes the use of SMEMDISK 
commands. 



Reducing $COMPRES, $C0PYUT1, and $COPY Operating Times 

You can reduce the time it takes for SCOMPRES, SCOPYUTl, or SCOPY 
operations by requesting dynamic storage. You specify the amount of dynamic 
storage when you load these utilities. The dynamic storage you specify is the 
amount of contiguous storage in the partition minus the size of the program(s). 

The following is an example of how you request the maximum dynamic storage 
available in the partition you are loading the utilities: 



> $L SCOMPRES,,* 

> $L SCOPYUTl,,* 

> $L SCOPY,,* 



For SCOMPRES, maximum performance is reached when you specify dynamic 
storage as the number of data sets times 32. You can determine the number of data 
sets by loading SDISKUTl and issuing the LS command. For SCOPYUTl and 
SCOPY, the more dynamic storage you request, the greater the performance 
improvement. 
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Reducing $EDXASM Compilation Time 



You can reduce the amount of time needed to compile a $EDXASM program by 
requesting the maximum number of overlays (6) when you load $EDXASM. The 
default is 6. Specifying the maximum reduces the number of storage loads required 
by $EDXASM. Use the OVERLAY (OV) option to specify the number of overlays. 
(Refer to the Installation and System Generation Guide for an explanation of using 
the OVERLAY option.) 



You can also reduce the amount of time required to compile or assemble programs 
by creating temporary work data sets for the SEDXASM compiler, the SSIASM 
assembler, and the SEDXLINK linkage editor. The $MEMDISK utihty enables you 
to create these data sets in unmapped storage. See the SJOBUTIL job stream in 
"Reducing Program Load Time" on page 8-7 for an example. 

In addition, you can decrease assembly or compilation time even further by copying 
the entire assembler or compiler and all associated overlays onto volumes created 
with the SMEMDISK utiHty. 

Note: Since unmapped storage is part of main memory, you will lose the volumes 
created with SMEMDISK in the event of a power failure or IPL. Use the volumes 
in unmapped storage only for work data sets, programs, and other files that you can 
recover if a power failure does occur. 



Improving Performance of EDL Instructions 



To improve performance, you can move supervisor modules that contain emulation 
support for specific EDL instructions and the supervisor module EDXALU from 
partition 1 to another partition. 



v.. 



For example, to improve the performance of BSCAM, you can change the link 
control data set as follows: 



* _ 


• 
• 
• 


PART 2 
*__ 


* EDX EMULATOR SUPPORT 

* 


- MAY BE INCLUDED IN PARTITION 1 TO 8 


INCLUDE EDXALU 

INCLUDE BSCAM 

* 


*30* EDL INSTRUCTION EMULATOR 
*13* BISYNC COMMUNICATION SUPPORT 


• 
• 
• 
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In this example, the BSCAM instruction set will show improved performance 
because EDXALU resides in the same partition as BSCAM. 

Note: If you move EDXALU from partition 1 , some performance degradation will 
occur for the supervisor modules that remain in partition 1 and that contain 
emulation support for EDL instructions. 



Reducing Program Load Time 






You can reduce the amount of time it takes the system to load programs by using 
the SPREFIND utiUty, fixed-head volumes, or the SMEMDISK utility. 

Using $PREFIND: You can use $PREFIND to reduce program load times when: 

• A program references a large number of data sets or overlays. 

• You load a program frequently from disk or diskette. 

• A program's environment (data sets/volumes) is not subject to frequent changes. 

The SFREFIND utility stores the physical address of all referenced data sets and 
overlays in the program header. Therefore, when you load the program for 
execution, the system does not have to search volume and data set directories to find 
the data sets or overlays. For a program requiring a large number of data sets or 
overlays, the time saving could be significant. 

The Operator Commands and Utilities Reference describes the use of $PREFIND in 
more detail. 

Using Fixed-head Volumes: By placing the EDX loader (SLOADER) on a 
fixed-head volume, no disk-seek operations are required. This decreases program 
load time. Allocate a fixed-head volume by using the SINITDISK utility (AF 
command) on the disk from which you IPL. Copy $LOADER to this volume. 
During IPL, the system uses the $LOADER on the fixed-head volume. If the 
$LOADER is not on the fixed-head volume, the system next goes to the IPL volume 
to use the $LOADER on the IPL volume. 

Using $MEMDISK: By placing the EDX loader (SLOADER) on a volume created by 
SMEMDISK, $LOADER also becomes storage-resident, which decreases program 
load time. Normally, you would have to run the SMEMDISK and SCOPYUTl 
utiUties interactively to load SMEMDISK and make SLOADER storage-resident. 
However, through the use of a SINITIAL program or SJOBUTIL, you can do this 
as part of the IPL process. 
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Setting Flags in the $TCBFLGS Word 



You can set flags in the STCBFLGS word that will override whatever is coded for 
WAITIOSR in the SSRPROF data set (explained in the Installation and System 
Generation Guide). The following example shows bit settings for $TCBFLGS. An 
explanation of the numbered items follows the example. 

Note; An x indicates that the system ignores the value of the bit. It only checks the 
and 1 bits indicated below. 



o 



Example 



XXXX XXXI xxxx xxxx 
xxxx XXX0 xxxx xxxx 

B 

xxxx xxxx oxxx xxxx 
xxxx xxxx ixxx xxxx 



CHECK IF I/O IS TO/FROM DYNAMIC/STATIC PARTITION 
DON'T CHECK; ISSUE I/O 

WAIT FOR ALLOCATION 

DON'T WAIT; TASK REMOVED FROM SYSTEM. ERROR 

MESSAGE IN $SYSL06. 



DEFAULTS 

XXXX XXXl OXXX XXXX 



4-bit mode 



Q Indicates the $TCBCHK flag. When it is set to 1 , the system checks to see if 
the I/O is to or from a static or dynamic partition. When it is set to 0, the system 
does not check; it issues the I/O. 

Q Indicates the STCBWAIT flag. When it is set to 0, the system waits until 
segmentation registers are available to issue I/O. When it is set to 1, the system 
removes the task and issues an error message to $SYSLOG. 






Copy in the TCB equates as follows: 



COPY TCBEQU 



The hst of equates includes the following: 



$TCBCHK EQU X' 
$TCBWAIT EQU X' 

• 


0100' 
0080' 


• 
$TCBCHKB EQU 7 
$TCBWAIB EQU 8 

• 




• 




• 
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The sample program reads in STCBFLGS, turns off the check bit, and puts it back 
into STCBFLGS as follows: 



TCBGET FLAGWORD,$TCBFLGS 
SETBIT FLAGWORD,OFF,+$TCBCHKB 
TCBPUT FLAGWORD,$TCBFLGS 



FLAGWORD DATA F'O' 



%J 
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Chapter 9. Customizing Partitions 



This chapter describes when to customize partitions and the various ways you can 
customize partitions. 



When You Need to Customize Partitions 



You need to customize your partitions when you have written a supervisor module 
that 

• Performs I/O operations into itself 

• Performs I/O operations from itself 

• Contains one or more data control blocks (DCBs). 

If you have written a supervisor that does any of these things, you must customize 
your partitions so that the module resides in a static portion of the supervisor. 



Ways to Customize Partitions 

You can customize your partitions in three different ways: 

• Include the module before the module EDXSVCX in partition 1 . 

• Map an entire partition as static. 

• Map part of a partition as static. 

Including Your Supervisor Module before EDXSVCX 

To include your supervisor module before EDXSVCX, you must edit the hnk 
control data set ($LNKCNTL). Insert your module before the EDXSVCX module 
as in the following example: 



* , 



* SUPERVISOR SUPPORT 



PART 1 




VOLUME XS5002 




*OVLAREA OVLSTART OVLEND 


*23* 


INCLUDE EDXSYS 


*2* 


INCLUDE ASMOBJ,EDX002 


*]^* 


INCLUDE MYBUFFl 




INCLUDE EDXSVCX 


*]^* 



MUST BE FIRST AND IN PARTITION 1 



DEFAULT VOLUME FOR INCLUDE MODULES 
USER DEFINED OVERLAY AREA 
SYSTEM TABLES AND WORK AREA 
OUTPUT FROM USER SYSTEM GENERATION 
USER BUFFER AREA (MAPPED AREA) 
TASK SUPERVISOR 
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Mapping an Entire Partition as Static 

To map an entire partition as static, include the SUPVIO module in the partition. £^^ 

Including SUPVIO in a partition causes the entire supervisor area and any common I B 

area within the partition to be mapped as static. 

Note: The common area will be static only if the common base partition is 1 . 

Figure 9-1 on page 9-3 shows the mapping of static and dynamic partitions. 
Without SUPVIO, the supervisor area is dynamically mapped across partitions. The 
common area is mapped dynamically for partitions 9 to 32 and it can be either static 
or dynamic for partitions 2 through 8. Partition 1 must be static, but the supervisor 
modules after entry point EDXSVCX in data set SEDXDEFS can be dynamic. 

To include SUPVIO, edit the hnk control data set (SLNKCNTL), including 
SUPVIO in the partition you want to be static. If you include SUPVIO in a 
partition, you cause both common and supervisor areas to be mapped as static, even 
if you define a partition as dynamic. 

Note: Refer to the Installation and System Generation Guide for a more complete 
explanation of static and dynamic partitions and how to assign them. Information 
about the common base partition determined by the COMBASE keyword of the 
SYSCOMM statement is available in the Installation and System Generation Guide 
also. 

If you include SUPVIO, a supervisor module that you wrote for a previous version 
of EDX will work the same as it did in the previous version. If you do not include 
SUPVIO, you must reset the flags in the task issuing the I/O command for the 
supervisor module to work the same way as it did in the previous version. See 
"Setting Flags in the $TCBFLGS Word" on page 8-8 for information on setting 
these flags. 

Another advantage of using SUPVIO to map as static a supervisor module that 
performs I/O into itself is that you no longer need to acquire segmentation registers 
for every I/O operation. 






\J 
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The following figure shows the mapping if you include SUPVIO and the defaults 
when you do not include SUPVIO. An explanation of the numbered items follows 
the example. 



o 



MAPPING DEFAULTS WITHOUT 


SUPVIO: 










Part # 

ni 


Part Type 


Common Area 


Supervisor 


Area 


User Area 


COMBASE Type 


STATIC 


STATIC STATIC/DYNAMIC 


STATIC 


STATIC 


1 


STATIC 


N/A 


STATIC/DYNAMIC 


STATIC 


DYNAMIC 


2 - 8 


STATIC 


STATIC 


DYNAMIC 




STATIC 


STATIC 


2 - 8 


STATIC 


DYNAMIC 


DYNAMIC 




STATIC 


DYNAMIC 


2 - 8 


DYNAMIC 


STATIC 


DYNAMIC 




DYNAMIC 


STATIC 


2 - 8 


DYNAMIC 


DYNAMIC 


DYNAMIC 




DYNAMIC 


DYNAMIC 


9 - 32 


DYNAMIC 


STATIC 


N/A 




DYNAMIC 1 


[static 


9 - 32 


DYNAMIC 


DYNAMIC 


N/A 




DYNAMIC 1 


[dynamic 


MAPPING WITH 


SUPVIO INCLUDED: 










Part # 

1 


Part Type 


Common Area 
STATIC 


Supervisor 
STATIC 


Area 


User Area 
STATIC 


COMBASE Type 


STATIC 


STATIC 


1 


STATIC 


N/A 


STATIC 




STATIC 


DYNAMIC 


2 - 8 


STATIC 


STATIC 


STATIC 




STATIC 


STATIC 


2 - 8 


STATIC 


DYNAMIC 


STATIC 




STATIC 


DYNAMIC 


2 - 8 


DYNAMIC 


STATIC 


STATIC 




DYNAMIC 


STATIC 


2 - 8 


DYNAMIC 


DYNAMIC 


STATIC 




DYNAMIC 


DYNAMIC 



Figure 9-1. SUPVIO Mapping Example ^ 

Q Partition 1 must be static. 

Q The supervisor area is static up to the end of the system definition statements in 
partition 1. 

01 For 5-bit processors and extended I/O attachments, partitions 9 — 32 are treated 
as static since they are always mapped for I/O. 



v^ Hi 
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The following figures illustrate what happens to a dynamic or static partition in 
which you have included SUPVIO. The shaded portions illustrate areas that are not 
mapped for I/O operations. If you do not include SUPVIO, all of partitions 2 and 3 
would be shaded. Figure 9-3 indicates that SUPVIO has no effect on static 
partitions. 

Note: This figure has a common base partition of 1 . 



o 



Partition 3 



Partition 2 




Common 



Supervisor 



User 



BG0368 



Figure 9-2. SUPVIO in Dynamic Partitions. 



Partition 4 







k^ 
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Figure 9-3. SUPVIO in Static Partitions. 
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The following is a partial listing of the $LNKCNTL data set showing the modules 
that pertain to SUPVIO: 



* 






• 
• 
• 




* SUPERVISOR CODE i 

* PARTITION 1 MUST 

* 


BEING MOVED 
BE MOVED TO 


OUT OF 
HERE 


PART 2 
*INCLUDE 

* 


SUPVIO 




*28* 


MAKE SUPERVISOR AND COMMON AREA STATIC 


* 






• 
• 
• 




*PART 3 

*INCLUDE 

*PART 4 

*INCLUDE 

*PART 5 

*INCLUDE 

*PART 6 

*INCLUDE 

*PART 7 

*INCLUDE 

*PART 8 

*INCLUDE 
* 

* 


SUPVIO 
SUPVIO 
SUPVIO 
SUPVIO 
SUPVIO 
SUPVIO 




*28* 
*28* 
*28* 
*28* 
*28* 
*28* 


MAKE SUPERVISOR AND COMMON AREA STATIC 
MAKE SUPERVISOR AND COMMON AREA STATIC 
MAKE SUPERVISOR AND COMMON AREA STATIC 
MAKE SUPERVISOR AND COMMON AREA STATIC 
MAKE SUPERVISOR AND COMMON AREA STATIC 
MAKE SUPERVISOR AND COMMON AREA STATIC 


* PROGRAMMING NOTES 

* 


• 
• 
• 
*28* MAKES ALL THE COMMON AND SUPERVISOR AREA OF EACH PARTITION THAT 

* SUPVIO IS INCLUDED IN STATIC (ONLY VALID FOR EXTENDED ADDRESS 

* MODE SUPPORT). 



Figure 9-4. Partial SLNKCNTL Data Set Showing SUPVIO 



Mapping Part of a Partition as Static 

To map part of a partition as static, include DYNSTART and DYNEND in the 
SLNKCNTL data set (see "Editing SLNKCNTL" on page 9-6 for an example). 
You can use these modules, either together or separately, to make part of the 
supervisor in a static partition mapped for I/O segmentation registers. You can 
include DYNSTART in partitions 2-8 and DYNEND in partitions 1-8. 
However, if you include DYNEND in any partition, then you must include 
DYNEND in every supervisor partition. The default is to include DYNEND right 
before EDXINIT in partition 1 and the last supervisor module in partitions 2 — 8. 
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Notes: 

1 . If you limit the size of the unmapped I/O segmentation register area within your 
static partitions, you limit the number of I/O segmentation registers that the 
system can use for the partitions you defined as dynamic in the SSRPROF data 
set, explamed m the Installation and System Generation Guide. 

2. If you include SUPVIO in a partition, it overrides DYNSTART or DYNEND. 

3. If you include DYNSTART, link edit the supervisor, and the address of 
DYNSTART does not fall on a 2K boundary, the system rounds the dynamic 
supervisor area up to the nearest 2K boundary. 

4. If you include DYNEND, link edit the supervisor, and the address of 
DYNEND does not fall on a 2K boundary, the system rounds the dynamic 
supervisor area down to the nearest 2K boundary. 



Editing $LNKCNTL 



In order to include DYNSTART and/or DYNEND in a partition, you must edit the 
SLNKCNTL data set. The following examples show partition 2 in the SLNKCNTL 
data set. Example 1 illustrates partition 2 without DYNSTART or DYNEND 
included. Example 2 illustrates partition 2 with DYNSTART included. Example 3 
illustrates partition 2 with DYNEND included. Example 4 illustrates partition 2 
with DYNSTART and DYNEND included. Partition 2 is defined as static in the 
PARTS = operand of SSRPROF. 

Example 1: Partition 2 without DYNSTART or DYNEND included. 



PART 2 


• 
• 
• 




INCLUDE DISKIO 


*3* 


BASIC DISKETTE SUPPORT 


*INCLUDE DISKIOX 


*31* 


DYNAMIC DATA SET EXTENT SUPPORT-OPTIONAL 


INCLUDE D49624 


*3* 


4962/4964 DISK(ETTE) SUPPORT 


INCLUDE D4963A 


*3* 


4963/4967/DDSK DISK SUPPORT 


INCLUDE D4966A 


*3* 


4965/4966 DISKETTE SUPPORT 


INCLUDE DIDSKA 


*3* 


IDSK DISK(ETTE) SUPPORT 


*INCLUDE D1024 


*3,21* 


1024 BYTES/SECTOR DISKETTE SUPPORT 


*INCLUDE D4969A 


*3* 

• 
• 
• 


BASIC TAPE SUPPORT 



/■ 
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Figure 9-5 illustrates partition 2 without DYNSTART or DYNEND. The shaded 
region shows that the entire supervisor area is unmapped. 

Partition 2 




BG0370 

Figure 9-5. Unmapped Supervisor Area without DYNSTART or DYNEND Included. 
Example 2: Partition 2 with DYNSTART included. 



PART 2 


• 
• 
• 




INCLUDE MYBUFFl == 




USER BUFFER AREA (MAPPED AREA) 


INCLUDE DYNSTART == 




START OF I/O SEG REG UNMAPPED AREA 


INCLUDE DISKIO 


*3* 


BASIC DISKETTE SUPPORT 


*INCLUDE DISKIOX 


*31* 


DYNAMIC DATA SET EXTENT SUPPORT-OPTIONAL 


INCLUDE D49624 


*2* 


4962/4964 DISK(ETTE) SUPPORT 


INCLUDE D4963A 


*3* 


4963/4967/DDSK DISK SUPPORT 


INCLUDE D4966A 


*3* 


4965/4966 DISKETTE SUPPORT 


INCLUDE DIDSKA 


*3* 


IDSK DISK(ETTE) SUPPORT 


*INCLUDE D1024 


*3,21* 


1024 BYTES/SECTOR DISKETTE SUPPORT 


*INCLUDE D4969A 


*3* 

• 
• 
• 


BASIC TAPE SUPPORT 
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Figure 9-6 illustrates partition 2 with DYNSTART included. The shaded region 
shows that only the supervisor area following DYNSTART remains unmapped. 



Partition 2 



Mapped 

supervisor 

area 



MYBUFFI 



Supervisor 



User 



DYNSTART 



BG0371 



Figure 9-6. Unmapped Supervisor Area with DYNSTART Included. 
Example 3: Partition 2 with DYNEND included. 



PART 2 


• 
• 
• 




INCLUDE DISKIO 


*3* 


BASIC DISKETTE SUPPORT 


*INCLUDE DISKIOX 


*31* 


DYNAMIC DATA SET EXTENT SUPPORT-OPTIONAL 


INCLUDE D49624 


*3* 


4962/4964 DISK(ETTE) SUPPORT 


INCLUDE D4963A 


*3* 


4963/4967/DDSK DISK SUPPORT 


INCLUDE D4966A 


*3* 


4965/4966 DISKETTE SUPPORT 


INCLUDE DIDSKA 


*3* 


IDSK DISK(ETTE) SUPPORT 


*INCLUDE D1024 


*3,21* 


1024 BYTES/SECTOR DISKETTE SUPPORT 


*INCLUDE D4969A 


*3* 


BASIC TAPE SUPPORT 


INCLUDE DYNEND 


========== 


END OF I/O SEG REG UNMAPPED AREA 


INCLUDE MYBUFF2 == 


• 
• 
• 


USER BUFFER AREA (MAPPED AREA) 



ifV 
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Customizing Partitions 



Figure 9-7 illustrates partition 2 with DYNEND included. The shaded region 
shows that only the supervisor area before DYNEND remains unmapped. 

Partition 2 



Mapped 

supervisor 

area 




DYNEND 



BG0372 



Figure 9-7. Unmapped Supervisor Area with DYNEND Included. 
Example 4: Partition 2 with DYNSTART and DYNEND included. 






PART 2 




• 
• 
• 




INCLUDE 


MYBUFFl == 


========= 


USER BUFFER AREA (MAPPED AREA) 


INCLUDE 


DYNSTART == 


========= 


START OF I/O SEG REG UNMAPPED AREA 


INCLUDE 


DISKIO 


*3* 


BASIC DISKETTE SUPPORT 


*INCLUDE 


DISKIOX 


*31* 


DYNAMIC DATA SET EXTENT SUPPORT-OPTIONAL 


INCLUDE 


D49624 


*3* 


4962/4964 DISK(ETTE) SUPPORT 


INCLUDE 


D4963A 


*3* 


(UNMAPPED) 4963/4967/DDSK DISK SUPPORT 


INCLUDE 


D4966A 


*3* 


(UNMAPPED) 4965/4966 DISKETTE SUPPORT 


INCLUDE 


DIDSKA 


*3* 


IDSK DISK(ETTE) SUPPORT 


*INCLUDE 


D1024 


*3,21* 


1024 BYTES/SECTOR DISKETTE SUPPORT 


*INCLUDE 


D4969A 


*3* 


BASIC TAPE SUPPORT 


INCLUDE 


DYNEND 




END OF I/O SEG REG UNMAPPED AREA 


INCLUDE 


MYBUFF2 == 


• 
• 
• 


USER BUFFER AREA (MAPPED AREA) 



Notes: 

1. MYBUFFl and MYBUFF2 are illustrations of statically-defined user I/O buffer 
areas. 

2. Since you included DYNEND in partition 2, you must include DYNEND in 
every partition with supervisor code. The default for partition 1 is the module 
listed above EDXINIT, and the default for partitions other than 1 is the last 
module in that partition. 
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Customizing Partitions 



Figure 9-8 illustrates partition 2 with DYNSTART and DYNEND included. The 
shaded region shows that only the supervisor area between DYNSTART and 
DYNEND remains unmapped. 



rariiiion z 



Mapped f 

supervisor 

area 



Mapped 

supervisor 

area 



MYBUFF1 



Supervisor 



MYBUFF2 



User 



DYNSTART 



DYNEND 



BG0373 



Figure 9-8. Unmapped Supervisor Area with DYNSTART and DYNEND Included. 
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